Roots and WP Packages are independent open source projects, supported only by developers like you. We’ve been improving the WordPress developer experience since 2011, and your support keeps it independent.
Keeping Trellis Servers Updated
Trellis installs packages, but by default it doesn't upgrade them. Re-provisioning a server leaves Nginx, PHP, and MariaDB at whatever version is already installed. When one of them ships a security release, you need to upgrade it yourself.
How Trellis installs packages
Most packages are installed with apt_package_state: present, which installs a package if it's missing and otherwise leaves it alone. A few security-related packages (openssh-server, fail2ban, and ferm) use apt_security_package_state: latest, so they're upgraded every time you provision.
These defaults live in group_vars/all/main.yml:
apt_package_state: present
apt_security_package_state: latest
apt_dev_package_state: latest
Nginx, PHP, and MariaDB come from their own repositories instead of Ubuntu's:
| Service | Repository | Version pinned by |
|---|---|---|
| Nginx | nginx.org mainline | Always the latest mainline release |
| PHP | packages.sury.org | php_version |
| MariaDB | MariaDB repository | mariadb_version |
Ubuntu's unattended-upgrades only covers Ubuntu's own repositories by default. It installs security updates for packages like Redis, Memcached, and OpenSSL, but never touches Nginx, PHP, or MariaDB.
Upgrading a service
To upgrade a single service, provision with apt_package_state=latest and the tag for that service's role. Upgrades stay within the version you've configured: PHP stays on your php_version (e.g. 8.3.x) and MariaDB stays on your mariadb_version.
Nginx
trellis provision --extra-vars apt_package_state=latest --tags nginx production
Confirm the version on the server:
nginx -v
PHP
trellis provision --extra-vars apt_package_state=latest --tags php production
This upgrades PHP and all of its extensions. Confirm the version on the server:
php -v
MariaDB
trellis provision --extra-vars apt_package_state=latest --tags mariadb production
Confirm the version on the server:
mariadb --version
Repeat for each environment, including staging and development.
Services restart automatically
The packages restart their own services when they're upgraded: PHP-FPM and MariaDB restart, and Nginx swaps the running process over to the new binary without dropping connections. If you want to be certain a service is running the new version, restart it on the server (e.g. sudo systemctl restart nginx).
Upgrading everything
To upgrade every package Trellis manages in one run, leave off --tags:
trellis provision --extra-vars apt_package_state=latest production
This runs the full server.yml playbook, so it takes longer and also applies any configuration changes you haven't provisioned yet.
Waiting for a security release
Security releases are often announced a day or two ahead of time, and packages can lag behind the official release. PHP builds on packages.sury.org usually land within hours of a release, but can take longer.
To see whether a new version is available, update the package lists on the server:
sudo apt-get update
Then compare the installed and candidate versions, swapping in the package you're checking:
apt-cache policy php8.3-fpm
Once the "Candidate" version is newer than "Installed", you're ready to provision.
The PHP role only refreshes the package lists if they're more than an hour old (apt_cache_valid_time). If you provision and PHP doesn't upgrade, run sudo apt-get update on the server and provision again.
Kernel and system updates
Kernel updates from unattended-upgrades don't take effect until the server reboots. Ubuntu creates /var/run/reboot-required when a reboot is needed:
cat /var/run/reboot-required
To upgrade the rest of the system's packages manually, run:
sudo apt-get upgrade
Staying informed
Security releases for the services Trellis installs are announced here:
When a release affects Trellis servers, we post upgrade steps on the Roots blog and Roots Discourse.
Last updated
Getting Started
The Basics
Security
Digging Deeper
Troubleshooting
Extensions
Sponsors
Roots is an independent open source org, supported only by developers like you. Become a sponsor.