How to install SuluCMS on Ubuntu or Debian Servers
You’ll learn how to pull the latest SuluCMS into a fresh server and get it running without having to wrestle with broken packages or cryptic PHP errors.
1. Pick the right OS version
Sulu requires a relatively recent Debian/Ubuntu release (Bionic/Bullseye is fine). If you’re on an older LTS, consider upgrading first—those old PHP runtimes will bite you later.
2. Install core dependencies
sudo apt update
sudo apt install -y php8.1 php8.1-cli php8.1-fpm php8.1-mysql \
php8.1-xml php8.1-curl php8.1-gd php8.1-intl \
git unzip libzip-dev zlib1g-dev
Why each piece?
- php‑mysql gives Sulu its database driver; without it composer will bail with “could not find driver”.
- xml, curl, gd, intl are used by Symfony components that Sulu relies on for everything from HTTP handling to image processing.
- git and unzip let you clone the repo and extract any bundled assets.
I’ve seen folks hit a wall right after installing php8.1‑cli, only to realize they had an old libzip that made Composer complain about missing PHP extensions.
3. Add the official PHP repository (if needed)
Ubuntu 20.04 ships with PHP 7.4 by default; you’ll need to pull in a newer version if you’re on that release:
sudo add-apt-repository ppa:ondrej/php -y sudo apt update sudo apt install -y php8.1-fpm php8.1-mysql ...
Skip this step if your distro already ships PHP 8.
4. Install Composer globally
Sulu is a Composer‑based project, so you’ll need Composer on the command line:
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
HASH="$(wget -q -O - https://composer.github.io/installer.sig)"
php -r "if (hash_file('sha384', 'composer-setup.php') === '$HASH') { echo 'verified'; } else { echo 'invalid'; unlink('composer-setup.php'); exit(1); }"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
Composer is the only sane way to pull Sulu’s dependencies; no more manual wget of individual bundles.
5. Grab the Sulu repo
git clone https://github.com/sulu/sulu.git /srv/sulucms cd /srv/sulucms git checkout stable-6.x # choose the latest stable branch
If you’re on a production server, skip the checkout step and just use the main branch; it points to the same code.
6. Create a database
Sulu expects MySQL/MariaDB or PostgreSQL. I’ll show the MySQL route:
sudo mysql -u root -p
Inside the MySQL shell:
CREATE DATABASE suludb DEFAULT CHARACTER SET utf8mb4; GRANT ALL PRIVILEGES ON suludb.* TO 'sulu'@'localhost' IDENTIFIED BY 'StrongPassword!'; FLUSH PRIVILEGES; EXIT;
Replace StrongPassword! with something you actually remember, because Sulu will try to connect on every boot.
7. Configure the .env file
Copy the sample and edit it:
cp .env.dist .env nano .env
Change the following lines to match your database credentials:
DATABASE_URL="mysql://sulu:StrongPassword!@localhost:3306/suludb?serverVersion=8.0" APP_SECRET="[auto-generated]"
APP_SECRET can stay as the autogenerated string unless you’re doing a serious security review.
8. Install PHP extensions that Composer needs
Sulu uses Doctrine and Symfony components that depend on certain PHP extensions. If any of these are missing, composer install will fail.
sudo apt install -y php-zip php-mbstring php-bcmath php-xmlrpc
A common stumbling block: forgetting php-zip. Composer complains about “ZipArchive not found”, and you’re left scratching your head. Installing it fixes the problem fast.
9. Run Composer
composer install --no-dev --optimize-autoloader
The --no-dev flag keeps the dev dependencies out of a production build, saving disk space and reducing attack surface. The autoload optimization speeds up every request by pre‑building class maps.
10. Migrate the database
Sulu uses Doctrine migrations:
php bin/console doctrine:migrations:migrate --no-interaction
If you see “Could not find a configuration file for the migration”, double‑check your .env values and that you ran Composer in the right directory.
11. Create an admin user
Sulu ships with a CLI command to bootstrap an administrator:
php bin/console sulucms:user:create admin@example.com --role ROLE_SUPER_ADMIN --password mysecret
Choose a strong password; Sulu will hash it automatically. Now you can log into the admin panel.
12. Configure a web server
If you’re using Nginx:
server {
listen 80;
server_name cms.example.com;
root /srv/sulucms/public;
index index.php index.html;
location / {
try_files $uri /index.php$is_args$args;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
}
}
Reload Nginx:
sudo systemctl reload nginx
For Apache, enable the mod_rewrite module and add a .htaccess file in /public. The Sulu docs cover that in more detail if you prefer Apache.
13. Final sanity check
Open your browser to http://cms.example.com/admin. Log in with the credentials you just created. If you see the dashboard, congratulations—you’ve got a working SuluCMS instance on a clean Ubuntu/Debian server.
If something goes sideways (composer errors, missing PHP extensions), search the exact error message; most people have hit those walls before and posted solutions on Stack Overflow or the Sulu Slack channel. The key is to keep your dependencies up‑to‑date and your .env accurate—Sulu will thank you for it.
