Operating System Debian

How to Install Bolt CMS 6 on Debian 13 (Trixie) with Nginx and MariaDB

Set up Bolt CMS 6 on Debian 13 with Nginx, PHP-FPM, MariaDB and Composer, from an empty server to a working admin login. Notes for Debian 12 included.

Bolt is an open-source content management system built on Symfony. This guide installs the current Bolt 6 series on Debian 13 (Trixie) with Nginx, PHP-FPM and MariaDB, and ends with a working site and an administrator login at /bolt. Debian 12 (Bookworm) works with the same steps; the one difference is the PHP version in the socket path.

Bolt is actively maintained: the 6.1 series receives regular releases, and the project states that only the latest minor release is supported. Bolt 6 requires PHP 8.2 or newer. Debian 13 ships PHP 8.4 and Debian 12 ships PHP 8.2, so the distribution packages are sufficient and no third-party PHP repository is needed. Debian 9 is long past its end of life and cannot run Bolt 6.

Requirements

  • A Debian 13 server and a user with sudo rights. The examples use deploy.
  • A domain name pointing at the server, example.com below. Bolt's documentation notes that the site must be reached by a host name for authentication to work.
  • About 1 GB of free memory while Composer installs the dependencies.

Install Nginx, PHP, MariaDB and Composer

sudo apt update
sudo apt install -y nginx mariadb-server composer unzip git \
  php-fpm php-cli php-mysql php-sqlite3 php-curl php-gd php-intl \
  php-mbstring php-xml php-zip

These packages cover the extensions in Bolt's requirements list (PDO with the MySQL driver, curl, gd, dom, xml, simplexml, zip, intl, mbstring and the ones built into PHP itself). Confirm the PHP version and note the MariaDB version, which you need in a moment:

php -v
mariadb --version

Create the database

Open the MariaDB shell as the database root user:

sudo mariadb

Create a database and an account for Bolt. Choose your own password and avoid the characters @, :, / and # in it, because the password becomes part of a URL later:

CREATE DATABASE bolt CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'bolt'@'localhost' IDENTIFIED BY 'change-this-password';
GRANT ALL PRIVILEGES ON bolt.* TO 'bolt'@'localhost';
EXIT;

Create the Bolt project

Bolt is installed with Composer from its project skeleton. Create the target directory, owned by your own user, and run Composer as that user, not as root:

sudo install -d -o deploy -g deploy /var/www/bolt
cd /var/www
composer create-project bolt/project bolt

Composer downloads Bolt and its dependencies into /var/www/bolt. The web root is the public/ directory inside it; Bolt does not support placing all of its files inside the web root.

Configure the database connection

The skeleton's .env file defaults to an SQLite database. Override it in a file named .env.local, which takes precedence and is not overwritten by updates:

cd /var/www/bolt
nano .env.local

Add one line, using your own password and the MariaDB version that mariadb --version printed, followed by -MariaDB:

DATABASE_URL=mysql://bolt:"change-this-password"@127.0.0.1:3306/bolt?serverVersion=11.8.3-MariaDB&charset=utf8mb4

The serverVersion parameter is required. The comments in Bolt's .env file say that the server version must be configured either there or in config/packages/doctrine.yaml.

Run the Bolt setup

php bin/console bolt:setup --no-fixtures

The command creates the database tables, generates a new APP_SECRET in .env, and asks for the user name, password, e-mail address and display name of the first user. With --no-fixtures the database starts empty; leave the option out and answer the prompt with yes if you want dummy content to explore.

Check the result:

php bin/console bolt:info

For a public site, switch Symfony to production mode by adding a second line to .env.local and rebuilding the cache:

echo 'APP_ENV=prod' >> .env.local
php bin/console cache:clear

Set file permissions

PHP-FPM runs as www-data. Bolt's documentation lists five directories that the web server must be able to write: config/, public/files/, public/theme/, public/thumbs/ and var/. Give them to the www-data group and apply the modes from the documentation:

cd /var/www/bolt
sudo chgrp -R www-data config public/files public/theme public/thumbs var
for dir in config/ public/files/ public/theme/ public/thumbs/ var/ ; do
    sudo find $dir -type d -print0 | sudo xargs -0 chmod u+rwx,g+rwxs,o+rx-w
    sudo find $dir -type f -print0 | sudo xargs -0 chmod u+rw-x,g+rw-x,o+r-wx
done

Repeat this block whenever you have run a console command as deploy that writes to var/, such as cache:clear; otherwise the new cache files are not writable for the web server.

Configure Nginx

Create /etc/nginx/sites-available/bolt.conf. The location blocks follow the Nginx configuration in Bolt's documentation, reduced to the essentials:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;

    root /var/www/bolt/public;
    index index.php;

    access_log /var/log/nginx/example.com.access.log;
    error_log  /var/log/nginx/example.com.error.log;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location = /bolt {
        try_files $uri /index.php$is_args$args;
    }
    location ^~ /bolt/ {
        try_files $uri /index.php$is_args$args;
    }

    location ^~ /thumbs {
        try_files $uri /index.php;
        expires max;
    }

    location ~ [^/]\.php(/|$) {
        try_files /index.php =404;
        fastcgi_split_path_info ^(.+?\.php)(/.*)$;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTP_PROXY "";
        fastcgi_param HTTPS $https if_not_empty;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        include fastcgi_params;
    }

    # Hidden files, except the ACME challenge directory
    location ~ /\.(?!well-known) {
        deny all;
    }

    location ~* /(.*)\.(markdown|md|twig|yaml|yml)$ {
        deny all;
    }
}

On Debian 12 the socket is /run/php/php8.2-fpm.sock. Enable the site, remove the default one, test and reload:

sudo ln -s /etc/nginx/sites-available/bolt.conf /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Log in and secure the site

Open http://example.com/ for the front page and http://example.com/bolt for the admin panel, and log in with the user you created during setup.

Before you use that login over the internet, add a TLS certificate. With Certbot from the Debian repositories:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com

Updates and troubleshooting

  • Updating Bolt. Bolt is a Composer project, so new releases are installed with composer update in /var/www/bolt. Back up the database and the project directory first, read the release notes, and reapply the permissions block afterwards.
  • Nginx offers index.php as a download. The fastcgi_pass line does not match an existing socket. List /run/php/ to see the real name.
  • HTTP 500 after switching to production mode. Look in var/log/ inside the project. The usual cause is that var/ is not writable for www-data.
  • Database connection errors during setup. Re-check the DATABASE_URL line: the password is in double quotes, and serverVersion matches your MariaDB release.

Bolt's own documentation is at docs.boltcms.io, and the project skeleton with its installation notes is the bolt/project repository.

Frequently asked questions

Can I use SQLite instead of MariaDB?

Yes, and it is the default. Skip the database section and the .env.local database line; Bolt then stores its data in var/data/bolt.sqlite, which the permissions block already covers. Bolt's .env file also contains a PostgreSQL example.

How do I add another administrator later?

Run php bin/console bolt:add-user --admin in the project directory and answer the prompts, or create the user in the admin panel.

Why not install Bolt 3 as older guides do?

Bolt 3 was written for PHP 5.5 to 7 and is not supported any more. The project only supports the latest minor release of the current major version, and its architecture changed completely with the move to Symfony.

Does Bolt work with Apache?

Yes. Bolt's requirements name Apache with mod_rewrite as the other supported production web server; the project ships .htaccess rules for it, so the virtual host only needs public/ as its document root and AllowOverride All.

Share story:

Continue reading other guides on How VPS.