### Full Project Setup with Trellis and Bedrock

Source: https://context7.com/roots/trellis/llms.txt

Follow these steps to clone Trellis and Bedrock, install dependencies, configure environments, and provision servers for a new WordPress project.

```bash
# 1. Clone Trellis alongside a Bedrock site
mkdir example.com && cd example.com
git clone --depth=1 https://github.com/roots/trellis.git trellis
git clone https://github.com/roots/bedrock.git site

# Directory structure:
# example.com/
# ── trellis/   ← this repository
# ── site/      ← Bedrock WordPress

cd trellis

# 2. Install Ansible dependencies
pip install -r requirements.txt
ansible-galaxy install -r galaxy.yml -p vendor/roles

# 3. Configure your development site
# Edit group_vars/development/wordpress_sites.yml:
#   canonical: example.test
# Edit group_vars/development/vault.yml:
#   vault_mysql_root_password: devpw
#   vault_wordpress_sites.example.com.env.db_password: devpw

# 4. Provision the development environment
ansible-playbook dev.yml -e env=development

# 5. Configure production
# Edit hosts/production: add your server IP
# Edit group_vars/production/wordpress_sites.yml: set repo, domain
# Edit group_vars/production/vault.yml: set all passwords and salts
ansible-vault encrypt group_vars/production/vault.yml

# 6. Provision production server
ansible-playbook server.yml -e env=production

# 7. Deploy the site
ansible-playbook deploy.yml -e "site=example.com env=production"
```

--------------------------------

### Install npm dependencies for Sage theme

Source: https://context7.com/roots/trellis/llms.txt

Installs npm dependencies locally for the Sage theme. Ensure you are in the correct directory.

```yaml
- name: Install npm dependencies
  command: npm ci
  delegate_to: localhost
  args:
    chdir: "{{ project_local_path }}/web/app/themes/sage"
```

--------------------------------

### Ansible Inventory Files (INI)

Source: https://context7.com/roots/trellis/llms.txt

Example Ansible inventory files for different environments (production, staging, development), mapping hostnames/IPs to Ansible groups.

```ini
# hosts/production
[production]
203.0.113.10

[web]
203.0.113.10

# hosts/staging
[staging]
203.0.113.20

[web]
203.0.113.20

# hosts/development (Lima VM default)
[development]
192.168.56.5

[web]
192.168.56.5
```

--------------------------------

### Apply Rules to Groups/Hosts

Source: https://github.com/roots/trellis/blob/master/roles/ferm/README.md

Demonstrates how to apply firewall rules scoped to specific groups or hosts using `ferm_input_group_list` or `ferm_input_host_list`. This example opens HTTP and HTTPS ports using the `dport_accept` template and specifies a filename for the configuration.

```yaml
ferm_input_group_list:
  - type: "dport_accept"
    dport: ["http", "https"]
    filename: "nginx_accept"
```

--------------------------------

### Common Trellis CLI Commands

Source: https://context7.com/roots/trellis/llms.txt

Examples of common `trellis-cli` commands that wrap `ansible-playbook` for various deployment and management tasks.

```bash
# Common trellis-cli commands (wraps ansible-playbook):
trellis up                                    # provision development VM
trellis deploy production example.com         # deploy to production
trellis rollback production example.com       # rollback last deploy
trellis ssh production example.com            # SSH into production server
trellis db open development example.com       # open DB in GUI app
trellis vault encrypt production              # encrypt vault file
trellis info production                       # show server info
```

--------------------------------

### Configure Port Acceptance with dport_accept Template

Source: https://github.com/roots/trellis/blob/master/roles/ferm/README.md

Use the `dport_accept` template within `ferm_input_list` to open specific ports. This example configures TCP ports for HTTP and HTTPS, allowing any source IP address, and names the resulting configuration file `nginx_accept`.

```yaml
ferm_input_list:
    # Choose the template to use.
    # REQUIRED: It can be either `dport_accept` or `dport_limit`.
  - type: "dport_accept"

    # Which protocol should be used?
    # OPTIONAL: Defaults to tcp.
    protocol: "tcp"

    # Which ports should be open?
    # REQUIRED: It can be the port value or a service in `/etc/services`.
    dport: ["http", "https"]

    # Which IP addresses should be white listed?
    # OPTIONAL: Defaults to an empty list.
    saddr: []

    # Should all IP addresses be white listed?
    # OPTIONAL: Defaults to true.
    accept_any: true

    # Which filename should be written out?
    # OPTIONAL: Defaults to the first port listed in `dport`.

    # The filename which will get written to `/etc/ferm/filter-input.d/nginx_accept`.
    filename: "nginx_accept"

    # Should this rule be deleted?
    # OPTIONAL: Defaults to false.
    delete: false
```

--------------------------------

### Compile assets for Sage theme

Source: https://context7.com/roots/trellis/llms.txt

Compiles assets locally for the Sage theme. This command should be run after dependencies are installed.

```yaml
- name: Compile assets
  command: npm run build
  delegate_to: localhost
  args:
    chdir: "{{ project_local_path }}/web/app/themes/sage"
```

--------------------------------

### Fail2ban Custom Services Configuration

Source: https://github.com/roots/trellis/blob/master/roles/fail2ban/README.md

Example of how to define additional services for Fail2ban to monitor. This configuration is typically placed in group_vars.

```yaml
# Which additional services should fail2ban monitor?
# You can define multiple services as a standard yaml list.
fail2ban_services_custom:
    # The name of the service
    # REQUIRED.
  - name: ssh

    # Is it enabled?
    # OPTIONAL: Defaults to "true" (must be a string).
    enabled: "true"

    # What port does the service use?
    # Separate multiple ports with a comma, no spaces.
    # REQUIRED.
    port: ssh

    # What protocol does the service use?
    # OPTIONAL: Defaults to the protocol listed above.
    protocol: tcp

    # Which filter should it use?
    # REQUIRED.
    filter: sshd

    # Which log file should it monitor?
    # REQUIRED.
    logpath: /var/log/auth.log

    # How many times can they try before getting banned?
    # OPTIONAL: Defaults to the maxretry listed above.
    maxretry: 6

    # What should the default ban action be?
    # OPTIONAL: Defaults to the action listed above.
    action: action_

    # How should the ban be applied?
    # OPTIONAL: Defaults to the banaction listed above.
    banaction: iptables-multiport


```

--------------------------------

### MariaDB Role Configuration

Source: https://context7.com/roots/trellis/llms.txt

Installs MariaDB and configures the root user. Supports InnoDB buffer pool and log file size tuning. Binary logging can be disabled for reduced I/O.

```yaml
# Override in group_vars/all/main.yml
mariadb_version: 10.11
```

```yaml
# Enable InnoDB buffer pool tuning (recommended for servers with >1GB RAM)
mariadb_set_innodb_buffer_pool_size: true
mariadb_innodb_buffer_pool_size: 512M
```

```yaml
mariadb_set_innodb_log_file_size: true
mariadb_innodb_log_file_size: 128M
```

```yaml
# Disable binary logging (default: true, reduces I/O on single-server setups)
mysql_binary_logging_disabled: true
```

--------------------------------

### Adding Custom Fail2ban Service

Source: https://github.com/roots/trellis/blob/master/roles/fail2ban/README.md

Example of adding a custom service like 'wordpress' to Fail2ban monitoring. This is done by defining it in group_vars and creating a corresponding filter file.

```yaml
fail2ban_services_custom:
  - name: wordpress
    filter: wordpress
    logpath: /var/log/auth.log
    maxretry: 2

```

--------------------------------

### Run Acorn optimize post-build hook

Source: https://context7.com/roots/trellis/llms.txt

Executes `wp acorn optimize` on the remote server after Composer dependencies are installed. This hook is part of the post-build process for Sage/Acorn.

```yaml
# deploy-hooks/build-after.yml

- name: Run Acorn optimize
  command: wp acorn optimize
  args:
    chdir: "{{ deploy_helper.new_release_path }}"
```

--------------------------------

### Xdebug Role Configuration for PHP Debugging

Source: https://context7.com/roots/trellis/llms.txt

Installs and configures Xdebug for PHP step debugging. Supports different modes like 'debug' and 'trigger', with customizable client ports and IDE keys.

```yaml
# group_vars/development/php.yml (Xdebug enabled by default in development)
xdebug_mode: 'debug'
xdebug_start_with_request: 'yes'
xdebug_discover_client_host: 1
xdebug_client_port: 9003
xdebug_idekey: PHPSTORM
```

```yaml
# Custom trigger-only mode (faster, only debugs when XDEBUG_TRIGGER is set)
xdebug_mode: 'debug'
xdebug_start_with_request: 'trigger'
xdebug_trigger_value: 'my-secret-trigger'
```

--------------------------------

### Redis Role Configuration for Object Caching

Source: https://context7.com/roots/trellis/llms.txt

Installs and configures Redis for WordPress object caching. Supports memory limits, persistence, and disabling specific commands for security.

```yaml
# Override in group_vars/all/main.yml or group_vars/production/main.yml
redis_maxmemory: 512mb
redis_maxmemory_policy: allkeys-lru
redis_requirepass: "secure_redis_password"   # set false to disable auth
```

```yaml
# Enable AOF persistence for durability (disable on cache-only setups)
redis_appendonly: "yes"
redis_appendfsync: everysec
```

```yaml
# Disabled commands for security
redis_disabled_commands:
  - FLUSHALL
  - KEYS
  - CONFIG
  - SHUTDOWN
```

--------------------------------

### Encrypted Secrets (YAML)

Source: https://context7.com/roots/trellis/llms.txt

Example of decrypted sensitive variables stored in an Ansible Vault file, including database passwords, salts, and admin credentials. Never commit unencrypted.

```yaml
# group_vars/production/vault.yml (decrypted view — NEVER commit unencrypted)
vault_mysql_root_password: "secure_root_password"

vault_users:
  - name: admin
    password: "secure_admin_password"
    salt: "random_salt_string"

vault_wordpress_sites:
  example.com:
    env:
      db_password: "secure_db_password"
      auth_key: "long_random_key"
      secure_auth_key: "long_random_key"
      logged_in_key: "long_random_key"
      nonce_key: "long_random_key"
      auth_salt: "long_random_salt"
      secure_auth_salt: "long_random_salt"
      logged_in_salt: "long_random_salt"
      nonce_salt: "long_random_salt"
```

--------------------------------

### Limit Port Connections with dport_limit Template

Source: https://github.com/roots/trellis/blob/master/roles/ferm/README.md

Utilize the `dport_limit` template within `ferm_input_list` to restrict connections on specified ports. This example limits TCP connections to the SSH port, allowing 5 hits every 300 seconds, with the rule not disabled by default.

```yaml
ferm_input_list:
    # Choose the template to use.
    # REQUIRED: It can be either `dport_accept` or `dport_limit`.
  - type: "dport_limit"

    # Which protocol should be used?
    # OPTIONAL: Defaults to tcp.
    protocol: "tcp"

    # Which ports should be open?
    # REQUIRED: It can be the port value or a service in `/etc/services`.
    dport: ["ssh"]

    # How many seconds to count in between the hits?
    # OPTIONAL: Defaults to 300.
    seconds: "300"

    # How many connections should be allowed per the amount of seconds you specified.
    # OPTIONAL: Defaults to 5.
    hits: "5"

    # Should this rule be disabled?
    # OPTIONAL: Defaults to false.
    disabled: false
```

--------------------------------

### Provision Local Development Environment

Source: https://context7.com/roots/trellis/llms.txt

Use `dev.yml` to provision a local LEMP stack with Xdebug and Mailpit. You can target specific roles or steps using tags for re-runs.

```bash
# Provision the local development environment (full stack)
ansible-playbook dev.yml -e env=development
```

```bash
# Provision only specific roles using tags
ansible-playbook dev.yml -e env=development --tags php,nginx
```

```bash
# Provision only the WordPress setup and install steps
ansible-playbook dev.yml -e env=development --tags wordpress
```

```bash
# Re-run only MariaDB setup
ansible-playbook dev.yml -e env=development --tags mariadb
```

--------------------------------

### Zero-Downtime Deploy

Source: https://context7.com/roots/trellis/llms.txt

Use `deploy.yml` for zero-downtime deployments of Bedrock sites. Specify the site and environment, and optionally a branch or tag.

```bash
# Deploy example.com to production
ansible-playbook deploy.yml -e "site=example.com env=production"
```

```bash
# Deploy a specific branch to staging
ansible-playbook deploy.yml -e "site=example.com env=staging branch=feature/my-branch"
```

```bash
# Deploy to production using a specific git tag
ansible-playbook deploy.yml -e "site=example.com env=production branch=v2.1.0"
```

--------------------------------

### Provision Remote Production/Staging Server

Source: https://context7.com/roots/trellis/llms.txt

Use `server.yml` to provision remote servers with a full LEMP stack, including security, databases, PHP, Nginx, and SSL. Specific components can be provisioned using tags.

```bash
# Provision a production server (full)
ansible-playbook server.yml -e env=production
```

```bash
# Provision a staging server
ansible-playbook server.yml -e env=staging
```

```bash
# Provision only Nginx and PHP on production
ansible-playbook server.yml -e env=production --tags nginx,php
```

```bash
# Provision Let's Encrypt SSL certificates only
ansible-playbook server.yml -e env=production --tags letsencrypt
```

```bash
# Provision only user accounts and SSH configuration
ansible-playbook server.yml -e env=production --tags users,sshd
```

--------------------------------

### View Full SSH Client Configuration

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Run this command on your server to view the full and active SSH client configuration for a specific domain.

```bash
ssh -G example.com
```

--------------------------------

### View Full SSH Server Configuration

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Run this command on your server to view the full and active SSH server configuration.

```bash
sshd -T
```

--------------------------------

### Trellis CLI Configuration

Source: https://context7.com/roots/trellis/llms.txt

Configuration for `trellis-cli`, including default database GUI app and shortcut URLs for `trellis open`.

```yaml
# trellis.cli.yml (in Trellis root directory)

# Default database GUI app for `trellis db open`
database_app: sequel-ace        # or: tableplus, sequel-pro

# Shortcut URLs for `trellis open`
open:
  admin: "https://example.com/wp/wp-admin"
  site: "https://example.com"
```

--------------------------------

### Copy compiled assets to release

Source: https://context7.com/roots/trellis/llms.txt

Copies compiled assets from the local Sage theme directory to the new release path on the server. Uses rsync with specific chmod options.

```yaml
- name: Copy compiled assets to release
  synchronize:
    src: "{{ project_local_path }}/web/app/themes/sage/public"
    dest: "{{ deploy_helper.new_release_path }}/web/app/themes/sage"
    group: no
    owner: no
    rsync_opts: --chmod=Du=rwx,--chmod=Dg=rx,--chmod=Do=rx,--chmod=Fu=rw,--chmod=Fg=r,--chmod=Fo=r
```

--------------------------------

### PHP Role Defaults Configuration

Source: https://context7.com/roots/trellis/llms.txt

Configures global PHP-FPM and PHP INI settings. These can be overridden per-environment. Includes OPcache and JIT tuning for production.

```yaml
# group_vars/all/main.yml (or group_vars/production/php.yml to override)
php_version: "8.3"
php_memory_limit: 256M
php_max_execution_time: 120
php_upload_max_filesize: 64M
php_post_max_size: 64M
php_max_input_vars: 3000

# OPcache tuning for production
php_opcache_enable: 1
php_opcache_memory_consumption: 256
php_opcache_max_accelerated_files: 10000
php_opcache_revalidate_freq: 60          # set to 0 in development for instant changes
php_opcache_validate_timestamps: 1

# JIT (PHP 8+) - disabled by default, enable for CPU-intensive workloads
php_opcache_jit: 'tracing'
php_opcache_jit_buffer_size: 64M

# Development-specific overrides in group_vars/development/php.yml
php_error_reporting: 'E_ALL'
php_display_errors: 'On'
xdebug_mode: 'debug'
xdebug_start_with_request: 'yes'
xdebug_discover_client_host: 1

```

--------------------------------

### Ansible Configuration (`ansible.cfg`)

Source: https://context7.com/roots/trellis/llms.txt

Ansible configuration file for Trellis, specifying custom plugin paths, inventory directory, roles path, and SSH connection options for performance.

```ini
[defaults]
# Custom plugin paths (Trellis ships its own filter, vars, and callback plugins)
callback_plugins = lib/trellis/plugins/callback
filter_plugins   = lib/trellis/plugins/filter
vars_plugins     = lib/trellis/plugins/vars

# Default inventory directory
inventory = hosts

# Vendor roles installed by galaxy.yml
roles_path = vendor/roles

# Performance: enables SSH pipelining (requires requiretty disabled in sudoers)
pipelining = True

force_handlers = True
force_color    = True

[ssh_connection]
# SSH options: agent forwarding, ControlMaster multiplexing, ed25519 key preference
ssh_args = -o ForwardAgent=yes -o ControlMaster=auto -o ControlPersist=60s \
           -o HostKeyAlgorithms=ssh-ed25519-cert-v01@openssh.com,ssh-rsa-cert-v01@openssh.com,ssh-ed25519,ssh-rsa
retries = 1
```

--------------------------------

### Environment and Cache Helpers Configuration

Source: https://context7.com/roots/trellis/llms.txt

Defines computed variables for site environment and object cache. Shows how `site_env` is assembled from various sources.

```yaml
# How site_env is assembled (for reference — do not override this file directly):
# site_env merges (in priority order, last wins):
#   1. wordpress_env_defaults          (db_host, db_name, wp_home, etc.)
#   2. vault_wordpress_env_defaults    (global secrets from vault)
#   3. redis_cache_env / memcached_cache_env  (if object cache enabled)
#   4. item.value.env                  (per-site env in wordpress_sites.yml)
#   5. vault_wordpress_sites[site].env (per-site secrets from vault)

# Add custom environment variables for all sites in all environments:
# group_vars/all/vault.yml:
# vault_wordpress_env_defaults:
#   my_api_key: "global_secret"

# Add per-site env vars in wordpress_sites.yml:
wordpress_sites:
  example.com:
    env:
      my_custom_var: "site_specific_value"
      db_host: "rds.us-east-1.amazonaws.com"   # remote DB override
```

--------------------------------

### Enable HTTP/2 and HTTP/3 in Nginx

Source: https://context7.com/roots/trellis/llms.txt

Enables HTTP/2 and HTTP/3 (QUIC) for SSL-enabled sites by default.

```yaml
nginx_http2_enabled: true
nginx_http3_enabled: true
```

--------------------------------

### Default Role Variables

Source: https://github.com/roots/trellis/blob/master/roles/ferm/README.md

Configure basic firewall settings like enabling the firewall, limiting port scans, and setting default policies for input, output, and forward chains. Also defines lists for custom rules and apt-cache validity time.

```yaml
ferm_enabled: true

ferm_limit_portscans: false

ferm_default_policy_input: DROP
ferm_default_policy_output: ACCEPT
ferm_default_policy_forward: DROP

ferm_input_list: []
ferm_input_group_list: []
ferm_input_host_list: []

apt_cache_valid_time: 86400
```

--------------------------------

### Customize SSH Ciphers, KexAlgorithms, and MACs

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Supplement default lists for `Ciphers`, `KexAlgorithms`, and `MACs` by defining `_extra` variables in `group_vars/all/security.yml` to accommodate older systems or less secure options.

```yaml
# group_vars/all/security.yml

# Allow CBC mode ciphers (less secure)
sshd_ciphers_extra:
  - aes256-cbc
  - aes192-cbc
  - aes128-cbc

# Accommodate older systems by allowing weaker kex algorithms (less secure)
sshd_kex_algorithms_extra:
  - diffie-hellman-group14-sha1
  - diffie-hellman-group-exchange-sha1
  - diffie-hellman-group1-sha1

# Accommodate older systems by allowing weaker MACs (less secure)
sshd_macs_extra:
  - umac-128@openssh.com
  - hmac-sha1
```

--------------------------------

### Global Server Variables (YAML)

Source: https://context7.com/roots/trellis/llms.txt

Configures global server settings such as PHP version, web root, and APT cache validity. Includes handling for raw variables containing Jinja2 special characters.

```yaml
# group_vars/all/main.yml
php_version: "8.3"
ntp_timezone: Etc/UTC
www_root: /srv/www
max_journal_size: 512M
apt_cache_valid_time: 3600
apt_package_state: present
composer_keep_updated: true

# Variables that contain Jinja2 special characters (e.g., WordPress salts) 
# are wrapped in {% raw %} to prevent template errors
raw_vars:
  - vault_mail_password
  - vault_mysql_root_password
  - vault_wordpress_sites
```

--------------------------------

### Open Backup SSH Connection

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Use this command to open a backup SSH connection before modifying SSH settings. The `ServerAliveInterval` option helps prevent the connection from being pruned as stale.

```bash
ssh -o ServerAliveInterval=60 root@12.34.56.78
```

--------------------------------

### Roll Back a Deploy

Source: https://context7.com/roots/trellis/llms.txt

Use `rollback.yml` to revert to the previous release by updating the `current` symlink. This can be done for a specific site and environment.

```bash
# Roll back to the previous release on production
ansible-playbook rollback.yml -e "site=example.com env=production"
```

```bash
# Roll back on staging
ansible-playbook rollback.yml -e "site=example.com env=staging"
```

--------------------------------

### Server User Management (YAML)

Source: https://context7.com/roots/trellis/llms.txt

Defines server users, groups, and SSH keys. SSH public keys can be loaded from local files or GitHub URLs.

```yaml
# group_vars/all/users.yml
admin_user: admin
web_user: web
web_group: www-data

users:
  - name: "{{ web_user }}"
    groups:
      - "{{ web_group }}"
    keys:
      - "{{ lookup('file', '~/.ssh/id_ed25519.pub', errors='ignore') }}"
      - https://github.com/myusername.keys       # load keys from GitHub
  - name: "{{ admin_user }}"
    groups:
      - sudo
    keys:
      - "{{ lookup('file', '~/.ssh/id_ed25519.pub', errors='ignore') }}"

web_sudoers:
  - "/usr/sbin/service php{{ php_version }}-fpm *"
```

--------------------------------

### Pre-Deploy Asset Build Hook (YAML)

Source: https://context7.com/roots/trellis/llms.txt

A sample Ansible playbook hook that runs before deployment to compile frontend assets.

```yaml
# deploy-hooks/build-before.yml

```

--------------------------------

### Xdebug Profiler Configuration

Source: https://context7.com/roots/trellis/llms.txt

Configure xdebug for profiling with specific output name and directory.

```yaml
xdebug_mode: 'profile'
xdebug_profiler_output_name: cachegrind.out.%p
xdebug_output_dir: /tmp
```

--------------------------------

### Let's Encrypt Role Configuration

Source: https://context7.com/roots/trellis/llms.txt

Automates TLS certificate issuance and renewal via acme-tiny. Allows customization of renewal schedule and minimum renewal age.

```yaml
# Customize renewal schedule (default: 1st, 11th, and 21st of the month)
letsencrypt_cronjob_daysofmonth: 1,11,21
```

```yaml
# Minimum certificate age (days) before renewal is attempted
letsencrypt_min_renewal_age: 60
```

```yaml
# Provide a pre-existing account key (optional; generate new if omitted)
# letsencrypt_account_key_source_file: /path/to/account.key
```

```yaml
# Or embed key content in Ansible Vault:
# letsencrypt_account_key_source_content: |
#   -----BEGIN RSA PRIVATE KEY-----
#   ...
#   -----END RSA PRIVATE KEY-----
```

--------------------------------

### WordPress Site Configuration (YAML)

Source: https://context7.com/roots/trellis/llms.txt

Defines settings for a specific WordPress site, including hosts, local path, repository, branch, multisite, SSL, and caching configurations.

```yaml
wordpress_sites:
  example.com:
    site_hosts:
      - canonical: example.com
        redirects:
          - www.example.com
    local_path: ../site                              # path to local Bedrock directory
    repo: git@github.com:myorg/example.com.git       # SSH format required
    repo_subtree_path: site                          # subdirectory with composer.json
    branch: main
    multisite:
      enabled: false
    ssl:
      enabled: true
      provider: letsencrypt                          # or 'self-signed', 'manual'
      hsts_max_age: 31536000
      hsts_include_subdomains: false
      hsts_preload: false
    cache:
      enabled: true                                  # FastCGI page cache
    object_cache:
      enabled: true
      provider: redis                                # or 'memcached'
      host: 127.0.0.1
      port: 6379
      database: 0
      prefix: "example_com_"
    xmlrpc:
      enabled: false
```

--------------------------------

### Verify build manifest exists

Source: https://context7.com/roots/trellis/llms.txt

Checks if the build manifest file exists after compilation. This is a crucial step to ensure assets were built correctly.

```yaml
- name: Verify build manifest exists
  stat:
    path: "{{ project_local_path }}/web/app/themes/sage/public/build/manifest.json"
  delegate_to: localhost
  register: manifest
  failed_when: not manifest.stat.exists
```

--------------------------------

### Extend sshd_config with SFTP Settings

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Use this child template to add SFTP-specific configurations to the sshd_config file. It extends the base template and adds a 'Match Group sftponly' block.

```jinja
# templates/sshd_config.j2

{% extends 'roles/sshd/templates/sshd_config.j2' %}

{% block main %}
{{ super() }}
Match Group sftponly
AllowAgentForwarding no
ChrootDirectory /home/%u
ForceCommand internal-sftp
PermitRootLogin no
{%- endblock %}
```

--------------------------------

### Nginx Role Defaults Configuration

Source: https://context7.com/roots/trellis/llms.txt

Sets global Nginx settings. Per-site Nginx configuration is handled separately. Includes settings for FastCGI and page caching.

```yaml
# roles/nginx/defaults/main.yml (override in group_vars/all/main.yml or higher)
nginx_worker_connections: 8000
nginx_fastcgi_buffers: 8 8k
nginx_fastcgi_buffer_size: 8k
nginx_fastcgi_read_timeout: 120s

# FastCGI page cache settings (applied when cache.enabled: true in wordpress_sites.yml)
nginx_cache_path: /var/cache/nginx
nginx_cache_size: 250m
nginx_cache_inactive: 1h
nginx_cache_duration: 30s
nginx_cache_background_update: "on"

```

--------------------------------

### Deploy Role Configuration Defaults

Source: https://context7.com/roots/trellis/llms.txt

Defines default configuration for the deploy role, including shared paths, templates, Composer flags, and hook lists. These can be overridden in environment-specific variable files.

```yaml
# roles/deploy/defaults/main.yml 

# Override any of these in group_vars/<env>/wordpress_sites.yml or group_vars/all/main.yml

# Git branch/tag/commit to deploy (overridden by -e branch=xxx)
project_version: "{{ branch | default(project.branch) | default('master') }}"

# Directories copied between releases to speed up deploys (not symlinked)
project_copy_folders:
  - vendor

# Symlinked shared paths persisted across deploys
project_shared_children:
  - path: web/app/uploads
    src: uploads

# Environment file template rendered on each deploy
project_templates:
  - name: .env config
    src: roles/deploy/templates/env.j2
    dest: .env
    mode: '0600'

# WP post-deploy automation
update_db_on_deploy: true
flush_rewrite_rules_on_deploy: true

# Composer flags
composer_no_scripts: true
composer_platform_requirements_check: true
composer_classmap_authoritative: true

# Hook file paths (add your own by appending to these lists)
deploy_build_before:
  - "{{ playbook_dir }}/deploy-hooks/build-before.yml"

deploy_build_after:
  - "{{ playbook_dir }}/roles/deploy/hooks/build-after.yml"
  - "{{ playbook_dir }}/deploy-hooks/build-after.yml"

deploy_finalize_before:
  - "{{ playbook_dir }}/roles/deploy/hooks/finalize-before.yml"

deploy_finalize_after:
  - "{{ playbook_dir }}/roles/deploy/hooks/finalize-after.yml"

```

--------------------------------

### WordPress Site-Specific Nginx and PHP-FPM Settings

Source: https://context7.com/roots/trellis/llms.txt

Configures per-site Nginx settings, PHP-FPM pool, HSTS, robots header, h5bp helpers, and runtime hardening.

```yaml
wordpress_sites:
  example.com:
    # ...
    h5bp:
      cache_file_descriptors: true
      extra_security: true
      cross_domain_fonts: true
      protect_system_files: true
      no_transform: false
      x_ua_compatible: true
```

```yaml
# group_vars/all/main.yml (global PHP-FPM pool tuning)
php_fpm_pm: dynamic
php_fpm_pm_max_children: 20
php_fpm_pm_start_servers: 4
php_fpm_pm_min_spare_servers: 2
php_fpm_pm_max_spare_servers: 8
php_fpm_pm_max_requests: 500
```

```yaml
# Optional hardening: run PHP-FPM as a non-deploy user
wordpress_runtime_hardened: true
wordpress_runtime_user: www-data
wordpress_runtime_group: www-data
wordpress_runtime_writable_paths:
  - shared/uploads
  - current/web/app/cache
```

--------------------------------

### Security Role: Firewall and Fail2ban Configuration

Source: https://context7.com/roots/trellis/llms.txt

Configures ferm firewall rules for Nginx, HTTP/3, and SSH, including IP whitelisting. Enables WordPress-specific fail2ban jails for enhanced security.

```yaml
# Firewall: accept ports for Nginx HTTP, HTTPS, HTTP/3 (UDP), and SSH
ferm_input_list:
  - type: dport_accept
    dport: [http]
    filename: nginx_accept
  - type: dport_accept
    dport: [https]
    filename: nginx_accept_https
  - type: dport_accept
    dport: ['443']
    protocol: udp
    filename: nginx_accept_http3
  - type: dport_accept
    dport: [ssh]
    saddr: "{{ ip_whitelist }}"     # restrict SSH to specific IPs
  - type: dport_limit
    dport: [ssh]
    seconds: 300
    hits: 20                        # rate-limit brute force attempts
```

```yaml
# IP allowlist for SSH (your IP is auto-detected via ipify)
ip_whitelist:
  - 127.0.0.0/8
  - "{{ ipify_public_ip | default('') }}"
```

```yaml
# SSH hardening
sshd_permit_root_login: false       # recommended for production
sshd_password_authentication: false
```

```yaml
# Enable WordPress-specific fail2ban jails
fail2ban_services_custom:
  - name: wordpress_wp_login
    filter: wordpress-wp-login
    enabled: "true"
    port: http,https
    logpath: "{{ www_root }}/**/logs/access.log"
  - name: wordpress_xmlrpc
    filter: wordpress-xmlrpc
    enabled: "true"
    port: http,https
    logpath: "{{ www_root }}/**/logs/access.log"
```

```yaml
fail2ban_bantime: 3600
fail2ban_maxretry: 3
```

--------------------------------

### SMTP Mail Configuration (YAML)

Source: https://context7.com/roots/trellis/llms.txt

Configures msmtp as the system MTA for outbound email, specifying the SMTP server, port, and credentials.

```yaml
# group_vars/all/mail.yml
mail_smtp_server: smtp.sendgrid.net:587
mail_admin: admin@example.com
mail_hostname: example.com
mail_user: apikey
mail_password: "{{ vault_mail_password }}"    # defined in group_vars/all/vault.yml
```

--------------------------------

### Fail2ban Role Variables

Source: https://github.com/roots/trellis/blob/master/roles/fail2ban/README.md

Default configuration variables for the Fail2ban role. These can be overridden in group_vars.

```yaml
fail2ban_loglevel: INFO

# Where should log outputs be sent to?
# SYSLOG, STDERR, STDOUT, file
fail2ban_logtarget: /var/log/fail2ban.log

# Where should the socket be created?
fail2ban_socket: /var/run/fail2ban/fail2ban.sock

# Which IP address, CIDR mark or DNS host should be ignored?
fail2ban_ignoreip: 127.0.0.1/8

# How long in seconds should the ban last for?
fail2ban_bantime: 600

# How many times can they try before getting banned?
fail2ban_maxretry: 6

# How should the file changes be detected?
# gamin, polling, auto
fail2ban_backend: polling

# Where should e-mail reports be sent to?
fail2ban_destemail: root@localhost

# How should the ban be applied?
# iptables, iptables-new, iptables-multiport, shorewall, etc.
fail2ban_banaction: iptables-multiport

# What e-mail action should be used?
# sendmail or mail
fail2ban_mta: sendmail

# What should the default protocol be?
fail2ban_protocol: tcp

# Which chain would the JUMPs be added into iptables-*
fail2ban_chain: INPUT

# What should the default ban action be?
# action_, action_mw, action_mwl
fail2ban_action: action_

# Trellis by default only monitors SSH connections
# For available parameters, see fail2ban_services_custom below.
fail2ban_services_default:
  - name: ssh
    port: ssh
    filter: sshd
    logpath: /var/log/auth.log

# In which folder did you place custom filters?
# Filters MUST have .conf.j2 extension to copied to the servers.
fail2ban_filter_templates_path: fail2ban_filters

```

--------------------------------

### Extend ssh_config with Host-Specific Options

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

This child template customizes the ssh_config file by adding host-specific options and then including the original global defaults. It extends the base template and uses '{{ super() }}' to include original content.

```jinja
# templates/ssh_config.j2

{% extends 'roles/sshd/templates/ssh_config.j2' %}

{% block main %}
# Host-specific configuration
Host example.com example2.com
	Port 2222
	ForwardAgent yes

# Global defaults for all Hosts
{{ super() }}
{%- endblock %}
```

--------------------------------

### Ansible Vault Commands (Bash)

Source: https://context7.com/roots/trellis/llms.txt

Commands for creating and editing encrypted Ansible Vault files to store sensitive information.

```bash
# Create and edit a vault file
ansible-vault create group_vars/production/vault.yml
ansible-vault edit group_vars/production/vault.yml
```

--------------------------------

### Toggle Xdebug SSH Tunnel

Source: https://context7.com/roots/trellis/llms.txt

Use `xdebug-tunnel.yml` to create or tear down a reverse SSH tunnel for Xdebug. This forwards the Xdebug port from the remote server to your local IDE.

```bash
# Enable Xdebug tunnel for the development VM
ansible-playbook xdebug-tunnel.yml -e xdebug_tunnel_inventory_host=192.168.56.5 -e xdebug_mode=debug
```

```bash
# Disable the Xdebug tunnel
ansible-playbook xdebug-tunnel.yml -e xdebug_tunnel_inventory_host=192.168.56.5 -e xdebug_mode=off
```

--------------------------------

### To Env Ansible Filter

Source: https://context7.com/roots/trellis/llms.txt

Converts a dictionary to `KEY="value"` format for generating `.env` files. The output is sorted by key and values are shell-escaped.

```python
# Input dict:
{
  "wp_env": "production",
  "db_name": "example_com_production",
  "db_password": "secret"
}

# Output (sorted by key, values shell-escaped):
# DB_NAME="example_com_production"
# DB_PASSWORD="secret"
# WP_ENV="production"
```

```yaml
# Used in roles/deploy/templates/env.j2:
{{ site_env | to_env }}
```

--------------------------------

### Select Sites Ansible Filter

Source: https://context7.com/roots/trellis/llms.txt

Filters the `wordpress_sites` dictionary by nested attributes. Used to compute site subsets based on various criteria like SSL, cache provider, or database host.

```yaml
# Get all sites with SSL enabled
sites_using_ssl: "{{ wordpress_sites | select_sites('ssl.enabled', 'true') }}"

# Get all sites using Let's Encrypt
sites_using_letsencrypt: >-
  {{ (wordpress_sites
      | select_sites('ssl.enabled', 'true')
      | select_sites('ssl.provider', 'eq', 'letsencrypt')).keys() | list }}

# Get all sites using Redis object cache
sites_using_redis: >-
  {{ (wordpress_sites
      | select_sites('object_cache.enabled', 'true')
      | select_sites('object_cache.provider', 'eq', 'redis')).keys() | list }}

# Get all sites with a remote (non-localhost) database
sites_using_remote_db: >-
  {{ (wordpress_sites
      | select_sites('env.db_host', 'ne', 'localhost')).keys() | list }}
```

--------------------------------

### Customize sshd_accept_env Variable

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Override the default `sshd_accept_env` variable in `group_vars/all/main.yml` to specify environment variables accepted by the SSH server.

```yaml
# group_vars/all/main.yml

sshd_accept_env:
  - LANG
  - LC_*
```

--------------------------------

### Designate Child Templates for SSH Configuration

Source: https://github.com/roots/trellis/blob/master/roles/sshd/README.md

Inform Trellis about custom child templates for `sshd_config` and `ssh_config` by defining the `sshd_config` and `ssh_config` variables in `group_vars/all/main.yml`.

```yaml
# group_vars/all/main.yml

sshd_config: "{{ playbook_dir }}/templates/sshd_config.j2"
ssh_config: "{{ playbook_dir }}/templates/ssh_config.j2"
```

--------------------------------

### Underscore Ansible Filter

Source: https://context7.com/roots/trellis/llms.txt

Converts dots to underscores in a string. Used to derive database names and usernames from domain names.

```yaml
# In group_vars/all/helpers.yml:
db_name: "{{ item.key | underscore }}_{{ env }}"
# example.com → example_com_production

db_user: "{{ item.key | underscore }}"
# example.com → example_com
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.