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
sudorights. The examples usedeploy. - A domain name pointing at the server,
example.combelow. 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 updatein/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_passline 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 thatvar/is not writable forwww-data. - Database connection errors during setup. Re-check the
DATABASE_URLline: the password is in double quotes, andserverVersionmatches 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.