Skip to content

WP Packages is our new WPackagist replacement that's 17x faster and updates every 5 minutes

Trellis

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

View as Markdown:

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

Sponsors

Roots is an independent open source org, supported only by developers like you. Become a sponsor.