Ga naar inhoud

Trellis Deployment Tool

Table of Contents

Overview

Trellis is an Ansible-based LEMP (Linux, Nginx, MySQL/MariaDB, PHP) stack for WordPress deployment and server management, part of the Roots ecosystem.

Key features: - Automated server provisioning - Zero-downtime deployments - SSL certificates via Let's Encrypt - Multiple environments (development, staging, production) - Security hardening and best practices - Built-in FastCGI caching - Dependency management with Ansible Galaxy

Resources: - roots.io/trellis - Trellis Documentation

Installing on Remote Servers

Complete Setup Process

Follow these steps to deploy WordPress with Trellis on a fresh server.

1. Install Ubuntu

Start with Ubuntu 18.04 LTS (or later).

Installation settings: - Location: Other → Europe → Netherlands - Hostname: client-production or client-staging (e.g., fitchef-production) - Real name: Client company name - Username: client-name - Password: Generated random password (store in 1Password) - Partition disks: Guided - use entire disk and setup LVM - Updates: Automatic security updates - Software selection: Standard system utilities + OpenSSH server

2. Setup SSH Access

On the server (logged in as the user you created):

mkdir .ssh && chmod 700 .ssh/
cd .ssh/
vi authorized_keys
chmod 600 authorized_keys

Add your public key:

macOS/Linux: 

cat ~/.ssh/id_rsa.pub

Windows (from Vagrant VM): 

cat ~/.ssh/id_rsa.pub

Paste the public key into authorized_keys on the server.

Verify SSH access: 

ssh username@server-ip

3. Configure Trellis

Update configuration files:

File: trellis/group_vars/production/wordpress_sites.yml

wordpress_sites:
  example.com:
    site_hosts:
      - canonical: example.com
        redirects:
          - www.example.com
    local_path: ../site
    repo: git@codepot.nl:client/example.git
    repo_subtree_path: site
    branch: master
    multisite:
      enabled: false
    ssl:
      enabled: true
      provider: letsencrypt
    cache:
      enabled: false

File: trellis/group_vars/production/vault.yml

vault_mysql_root_password: securepassword

vault_users:
  - name: "{{ admin_user }}"
    password: sudopassword  # Must match server user's sudo password
    salt: randomsalt

vault_wordpress_sites:
  example.com:
    admin_password: wppassword
    env:
      db_password: dbpassword

Warning

Ensure vault_users password matches the server admin user's sudo password.

Encrypt vault file: 

ansible-vault encrypt trellis/group_vars/production/vault.yml

4. Provision Server

Update hosts file:

Edit trellis/hosts/production:

[web]
your-server-ip

[production]
your-server-ip

Install Ansible roles:

cd trellis
ansible-galaxy install -r requirements.yml

Provision the server:

ansible-playbook server.yml -e env=production

Note

Windows users: Run this from inside the Vagrant VM.

This installs and configures: - Nginx - PHP 7.4+ (or 8.x depending on Trellis version) - MariaDB - SSL certificates - Security hardening - User accounts

5. Deploy Site

Prerequisites: - GitLab account with SSH access - SSH keys added (ssh-add -K on macOS)

Deploy:

cd trellis
./bin/deploy.sh production example.com

This: - Clones your repository - Installs Composer dependencies - Builds assets - Creates database - Activates SSL

6. Install WordPress

Visit your domain and complete the WordPress installation wizard.

Optional: Import database and media files using WP-CLI or WP Migrate DB Pro.

FastCGI Caching

Overview

Trellis includes built-in FastCGI caching support, which is faster and simpler than Varnish for WordPress sites.

Benefits: - Faster response times - Reduced server load - No additional software needed (built into Nginx)

Resources: Trellis FastCGI Caching Documentation

Configuration

Edit trellis/group_vars/production/wordpress_sites.yml:

wordpress_sites:
  example.com:
    cache:
      enabled: true
      duration: 30s
      skip_cache_uri: /wp-admin/|/xmlrpc.php|wp-.*.php|/feed/|index.php|sitemap(_index)?.xml
      skip_cache_cookie: comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in

Configuration options:

  • enabled: Enable or disable caching
  • duration: How long to cache pages (default: 30s)
  • skip_cache_uri: URIs to exclude from caching (regex)
  • skip_cache_cookie: Skip caching if these cookies are present

Tip

The skip_cache_uri setting is critical. It excludes permalinks and admin areas from being cached.

Apply Configuration

Provision server with new cache settings:

cd trellis
ansible-playbook server.yml -e env=production --tags=wordpress

WooCommerce Caching

For WooCommerce sites, additional configuration is needed to prevent caching of cart/checkout pages.

Resources: Trellis FastCGI Caching with WooCommerce

Backup Configuration

Overview

Trellis doesn't include backup functionality by default, but you can add it using the trellis-backup-role Ansible role.

Backups include: - Database dumps - Uploaded media files - Automatic uploads to Amazon S3

Resources: guilro/trellis-backup-role

1. Add Backup Role

Edit trellis/requirements.yml:

- name: trellis-backup
  src: guilro.trellis-backup
  version: 2.1.4

- name: lafranceinsoumise.backup
  version: 3.9.0

Install roles:

ansible-galaxy install -r requirements.yml

Edit trellis/server.yml:

roles:
  # ... existing roles
  - { role: trellis-backup, tags: [backup] }

2. Create Amazon S3 Bucket

Step 1: Create bucket

  1. Log in to AWS Console
  2. Go to S3 Console
  3. Click Create bucket
  4. Settings:
  5. Bucket name: lemone-backups-example.com
  6. Region: Frankfurt (eu-central-1)
  7. Defaults: Accept defaults for other settings

Step 2: Create IAM user

  1. Go to IAM Console
  2. Navigate to Users → Add user
  3. Settings:
  4. User name: lemone-example
  5. Access type: Programmatic access
  6. Permissions: Attach existing policies directly → Create policy

Step 3: Create IAM policy

Use this JSON policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucketMultipartUploads",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::lemone-backups-example.com"
    },
    {
      "Sid": "VisualEditor2",
      "Effect": "Allow",
      "Action": "s3:*",
      "Resource": "arn:aws:s3:::lemone-backups-example.com/*"
    }
  ]
}

Policy details: - Name: example-backup-bucket - Save: Create policy

Step 4: Attach policy to user

  1. Go back to Add user window
  2. Click refresh icon
  3. Search for backup-bucket
  4. Select your newly created policy
  5. Click Next → Create user
  6. Download CSV or copy Access Key ID and Secret Access Key to 1Password

Step 5: Test connection

Use Transmit (or another S3 client) to verify read/write access to the bucket.

3. Configure Backup Credentials

Edit trellis/group_vars/production/vault.yml:

example.com:
  env:
    backup_target_user: 'AKIAIOSFODNN7EXAMPLE'  # Access Key ID
    backup_target_pass: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'  # Secret Access Key

4. Configure Backup Settings

Edit trellis/group_vars/production/wordpress_sites.yml:

example.com:
  # ... other settings
  backup:
    enabled: true
    auto: true
    target: s3://s3-eu-central-1.amazonaws.com/lemone-backups-example.com
    schedule: '0 4 * * *'  # Daily at 4 AM
    purge: false  # Set to true to auto-delete old backups
    params:
      - 'export S3_USE_SIGV4="True"'

Note

The S3_USE_SIGV4 parameter is required for newer S3 regions like Frankfurt (eu-central-1).

5. Install Backup on Server

Provision server with backup role:

cd trellis
ansible-playbook server.yml -e env=production --tags=wordpress,backup

Troubleshooting: Source Mismatch

If you're migrating backups between different servers, you may encounter a "Source mismatch" error.

Fix: Add this parameter to wordpress_sites.yml:

backup:
  params:
    - 'export S3_USE_SIGV4="True"'
    - 'DUPL_PARAMS="$DUPL_PARAMS --allow-source-mismatch "'

Upgrading Trellis

Upgrading for Let's Encrypt V2

Older Trellis installations use Let's Encrypt V1 endpoint (deprecated). Upgrade Trellis to use the V2 endpoint.

Resources: GitHub Issue #1113

1. Upgrade Trellis Files

See: WordPress Roots: Updating Trellis

2. Switch to Correct Ansible Version

Newer Trellis versions require Ansible 2.8+:

brew switch ansible 2.8.5_1

Note

Check Trellis documentation for the recommended Ansible version.

3. Provision Server

Newer Trellis versions may ship with updated PHP versions (e.g., PHP 7.4, 8.0, 8.1).

cd trellis
trellis provision production

Warning

This may update PHP and other server software. Test on staging first!

4. Renew Let's Encrypt Certificates

Provision Let's Encrypt:

trellis provision --tags letsencrypt production

Then provision WordPress:

trellis provision --tags wordpress production

Troubleshooting: 502 Bad Gateway

If you see a 502 error after provisioning, PHP may not have started correctly.

Fix (SSH into server):

sudo service php7.4-fpm restart

Replace php7.4 with your PHP version (check with php -v).

Using Trellis on Windows

Overview

Running Trellis on Windows requires additional setup due to symlink limitations and path differences.

Prerequisites

  • VirtualBox installed
  • Vagrant installed
  • Administrator privileges

1. Setup Vagrant Box

Note

Run Vagrant as Administrator to allow symlinking.

Modify Vagrantfile:

Trellis requires changes to handle Windows symlinks. See Trellis GitHub Issue #8 for details.

2. Start Vagrant

vagrant up

Wait for provisioning to complete.

3. Generate PPK Key (for PuTTY)

Convert Vagrant private key to PPK format:

  1. Locate private key: trellis/.vagrant/machines/default/virtualbox/private_key
  2. Use PuTTYgen to convert to .ppk
  3. Use this .ppk file to connect via PuTTY

4. Install Node and Yarn in VM

SSH into VM and navigate to theme folder:

cd /srv/www/example.com/current/web/app/themes/theme-name

Install Yarn:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt-get update && sudo apt-get install yarn

Install Node 6 (or later):

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs

Note

Use Node 6 for compatibility with older Sage versions. Newer projects should use Node 18+.

5. Install Dependencies

From the VM:

yarn
composer install

6. Import Database

Place database export in /srv/www/example.com/current:

wp db import database.sql
wp search-replace 'https://production.com' 'https://example.test'

7. Setup SSH Keys

Generate and retrieve SSH key:

cat ~/.ssh/id_rsa.pub

Add to GitLab: - User Settings → SSH Keys → Add key

Add to deployment servers: - SSH as web user - Add key to ~/.ssh/authorized_keys

Troubleshooting

Yarn build not working?

npm rebuild node-sass --no-bin-links
npm install optipng-bin pngquant-bin mozjpeg gifsicle jpegtran-bin --no-bin-links

Note

Don't use yarn for this—it may break webpack.

Still not working?

rm -rf node_modules
yarn --no-bin-links --ignore-optional

See Also