From 16c41dac60b1e38fc0dbea7b688913b86423d27b Mon Sep 17 00:00:00 2001 From: Jasper Frumau Date: Wed, 28 Oct 2026 13:10:20 +0700 Subject: [PATCH] Remove the provisioning and updater guides, now posts on wpvilla.in NEW-MACHINE, PROJECT-SETUP, CRON, the provision README, the updater README and manual-update are covered by four posts and the existing cron post. Point the Trellis README, repository layout notes and the root README at the posts. The trellis-updater script stays. --- AGENTS.md | 2 +- CHANGELOG.md | 1 + CLAUDE.md | 1 - README.md | 2 +- trellis/README.md | 52 +- trellis/provision/CRON.md | 397 ------------- trellis/provision/NEW-MACHINE.md | 317 ---------- trellis/provision/PROJECT-SETUP.md | 915 ----------------------------- trellis/provision/README.md | 86 --- trellis/security/README.md | 2 +- trellis/updater/README.md | 256 -------- trellis/updater/manual-update.md | 115 ---- 12 files changed, 10 insertions(+), 2136 deletions(-) delete mode 100644 trellis/provision/CRON.md delete mode 100644 trellis/provision/NEW-MACHINE.md delete mode 100644 trellis/provision/PROJECT-SETUP.md delete mode 100644 trellis/provision/README.md delete mode 100644 trellis/updater/README.md delete mode 100644 trellis/updater/manual-update.md diff --git a/AGENTS.md b/AGENTS.md index 6ef91e6..3ba9b23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # Repository Guidelines ## Project Structure & Module Organization -- **trellis/** - Trellis-specific: `backup/`, `monitoring/`, `provision/`, `updater/` +- **trellis/** - Trellis-specific: `backup/`, `monitoring/`, `updater/` - **wp-cli/** - WordPress CLI tools: `content-creation/`, `diagnostics/`, `migration/` - **scripts/** - Utilities: `backup/`, `monitoring/`, `git/create-pr.sh`, `sync/rsync-theme.sh` - **docs/** - Design docs at the top level; guides in subdirectories: `nginx/` (server configs), `troubleshooting/` (server/WP), `bedrock/` (Composer workflows), `wordpress-utilities/` (copy-paste components) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c4188d..86abb62 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Removed +- **The provisioning and updater guides**, now four posts on wpvilla.in: [a new Mac for Trellis](https://wpvilla.in/new-mac-trellis-development-setup-lima-composer-node/), [cloning an existing project](https://wpvilla.in/clone-trellis-bedrock-project-lima-vm-first-provision/), [updating Trellis](https://wpvilla.in/update-trellis-without-losing-customisations-rsync-excludes/) and [provision tags and the PHP upgrade](https://wpvilla.in/trellis-provision-tags-php-version-upgrade-checklist/). The cron guide is covered by the existing [WP-Cron interval post](https://wpvilla.in/trellis-wp-cron-interval-scheduled-posts-late-cron-interval/). `trellis/provision/` is gone, as are the updater README and `manual-update.md`; the `trellis-updater` script stays. - **The content-creation guides**, now three posts on wpvilla.in: [creating pages from block markup](https://wpvilla.in/create-wordpress-pages-block-markup-wp-cli-trellis-vm-production/), [block patterns as PHP files](https://wpvilla.in/wordpress-block-pattern-php-files-headers-escaping-images/) and [pattern layout rules](https://wpvilla.in/wordpress-block-pattern-layout-alignfull-grid-spacing-rules/). `PAGE-CREATION.md`, `PATTERN-REQUIREMENTS.md` and the folder README are gone; the scripts and the example stay. - **The migration guides**, now four posts on wpvilla.in: [migrating a site to Trellis and Bedrock](https://wpvilla.in/migrate-wordpress-to-trellis-bedrock-step-by-step/), [testing before the DNS cutover](https://wpvilla.in/trellis-migration-test-etc-hosts-letsencrypt-dns-cutover/), [migrating several sites onto one server](https://wpvilla.in/migrate-multiple-wordpress-sites-one-trellis-server/) and [wp search-replace for domain and path changes](https://wpvilla.in/wp-search-replace-wordpress-url-domain-https-bedrock-paths/). `wp-cli/migration/` is gone, and the README, `CLAUDE.md` and `wp-cli/README.md` no longer point at it. - **The documentation feature.** The guides are moving to [wpvilla.in](https://wpvilla.in/), so wp-ops no longer searches or links documentation. diff --git a/CLAUDE.md b/CLAUDE.md index 5200efe..906989f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,6 @@ This is a collection of tools, scripts, and documentation for WordPress operatio - **trellis/** - Trellis-specific tools and workflows - `trellis/backup/` - Ansible playbooks for database/files backup, pull, and push operations - `trellis/monitoring/` - Nginx log monitoring and traffic analysis - - `trellis/provision/` - Provisioning guides and command reference - `trellis/security/` - fail2ban WordPress protection and manual IP blocking guides - `trellis/updater/` - Safe Trellis update scripts - **wp-cli/** - WordPress command-line operations diff --git a/README.md b/README.md index 5325eb5..2ab49f8 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ sites are run with: | Area | What's there | Docs | |------|--------------|------| -| **Trellis** | Safe Trellis updates, provisioning reference, new-machine and project setup | [updater](trellis/updater/README.md) · [provision](trellis/provision/README.md) | +| **Trellis** | Safe Trellis updates (`trellis-updater`) | [guide](https://wpvilla.in/update-trellis-without-losing-customisations-rsync-excludes/) | | **Backups** | Timestamped database and uploads backups from any environment | [→](trellis/backup/README.md) | | **Monitoring** | AI-crawler traffic, error surfacing, traffic by country, cron-scheduled reports | [→](trellis/monitoring/README.md) | | **Security** | Malware scanners with checksum verification, fail2ban, manual IP blocking, AbuseIPDB lookup | [scanners](wp-cli/security/README.md) · [server](trellis/security/README.md) | diff --git a/trellis/README.md b/trellis/README.md index 0288a5b..ccb2aa1 100644 --- a/trellis/README.md +++ b/trellis/README.md @@ -20,7 +20,6 @@ This directory contains production-ready tools for: trellis/ ├── backup/ # Database & file sync Ansible playbooks ├── monitoring/ # Nginx log analysis & security monitoring -├── provision/ # Server setup & configuration guides ├── security/ # WordPress security tools (fail2ban, IP blocking) └── updater/ # Safe Trellis version upgrade tools ``` @@ -268,49 +267,12 @@ ssh web@yoursite.com "grep 'POST.*wp-login' /srv/www/yoursite.com/logs/access.lo ## 4. Provisioning & Setup -**Location:** `provision/` +The provisioning guides are on the blog: -Documentation and guides for server provisioning, configuration, and WordPress cron management. - -### Documentation - -| File | Purpose | -|------|---------| -| `README.md` | Quick provisioning command reference | -| `CRON.md` | WordPress cron system configuration | -| `NEW-MACHINE.md` | New server setup guide | -| `PROJECT-SETUP.md` | Initial project setup guide | - -### Key Topics - -**Provisioning Commands** -- Development environment setup -- Staging/production deployment -- PHP version upgrades with correct tags -- Nginx configuration updates - -**WordPress Cron Configuration** -- WP-Cron vs system cron -- Trellis default: system cron every 15 minutes -- Multisite cron configuration -- Verification and troubleshooting - -**PHP Version Upgrades** - -When upgrading PHP, **must** include these tags: - -```bash -trellis provision --tags php,nginx,wordpress-setup,users,memcached production -``` - -Critical tags: -- `php` - Installs new version -- `nginx` - Updates PHP-FPM socket configuration -- `wordpress-setup` - Creates PHP version-specific pool configuration -- `users` - **Critical**: Updates sudoers for PHP-FPM reload (deployments fail without this) -- `memcached` - Installs version-specific memcached extension - -**See also:** [provision/README.md](provision/README.md) and subdirectory documentation. +- [Setting up a new Mac for Trellis development](https://wpvilla.in/new-mac-trellis-development-setup-lima-composer-node/) +- [Cloning an existing Trellis and Bedrock project](https://wpvilla.in/clone-trellis-bedrock-project-lima-vm-first-provision/) +- [Trellis provision tags and the PHP upgrade](https://wpvilla.in/trellis-provision-tags-php-version-upgrade-checklist/) +- [WP-Cron on Trellis: the interval and how to change it](https://wpvilla.in/trellis-wp-cron-interval-scheduled-posts-late-cron-interval/) --- @@ -354,9 +316,7 @@ git add -A git commit -m "Update Trellis to latest version" ``` -**See also:** -- [updater/README.md](updater/README.md) - Complete updater documentation -- [updater/manual-update.md](updater/manual-update.md) - Manual update instructions +**See also:** [Updating Trellis without losing your customisations](https://wpvilla.in/update-trellis-without-losing-customisations-rsync-excludes/) --- diff --git a/trellis/provision/CRON.md b/trellis/provision/CRON.md deleted file mode 100644 index 8255b85..0000000 --- a/trellis/provision/CRON.md +++ /dev/null @@ -1,397 +0,0 @@ -# WordPress Cron with Trellis - -Why scheduled posts run late and how to change the interval: [Scheduled Posts Go Live Up to 15 Minutes Late on Trellis](https://wpvilla.in/trellis-wp-cron-interval-scheduled-posts-late-cron-interval/). - -## Overview - -Trellis automatically configures **system cron** instead of WordPress's built-in WP-Cron for more reliable scheduled task execution. - -## How It Works - -### Traditional WordPress (WP-Cron) - -Regular WordPress installations use **WP-Cron**, which only runs when someone visits your site: - -```php -// wp-config.php (standard WordPress) -define('DISABLE_WP_CRON', false); // Default behavior -``` - -**Problems with WP-Cron:** -- Only triggers on page visits (if site has low traffic, tasks may never run) -- Multiple simultaneous visitors can trigger multiple cron runs -- Adds overhead to every page load -- Unreliable timing for scheduled tasks - -### Trellis Approach (System Cron) - -Trellis disables WP-Cron and uses **system cron** for reliable, predictable execution: - -**1. WP-Cron is disabled.** `disable_wp_cron` defaults to `true` in -`trellis/group_vars/all/helpers.yml` (and `roles/deploy/vars/main.yml`): - -```yaml -disable_wp_cron: true -``` - -This sets the `DISABLE_WP_CRON` constant to `true` in WordPress configuration. - -**2. System cron job is created** by the `wordpress-setup` role at -`/etc/cron.d/wordpress-{site_name}` (dots in the site name become underscores): - -```bash -# Example: /etc/cron.d/wordpress-example_com -#Ansible: example.com WordPress cron -*/15 * * * * web cd /srv/www/example.com/current && wp cron event run --due-now > /dev/null 2>&1 -``` - -**What this does:** -- Runs every 15 minutes (*/15) -- Executes as the `web` user (same user that owns WordPress files) -- Changes to the current release directory -- Runs `wp cron event run --due-now` to process any due scheduled events -- Sends output to `/dev/null` (suppresses email notifications) - -### WordPress Multisite Cron - -For **WordPress multisite** installations, a separate job is written to -`/etc/cron.d/wordpress-multisite-{site_name}` so all subsites have their cron -events processed. Its default interval is **every 30 minutes**, not 15: - -```bash -# Example: /etc/cron.d/wordpress-multisite-demo_example_com -#Ansible: demo.example.com WordPress network cron -*/30 * * * * web cd /srv/www/demo.example.com/current && (wp site list --field=url | xargs -n1 -I % wp --url=% cron event run --due-now) > /dev/null 2>&1 -``` - -**What this does:** -- `wp site list --field=url` - Lists all site URLs in the network -- `xargs -n1 -I % wp --url=% cron event run --due-now` - Runs cron for each site individually -- Ensures scheduled events are processed for all subsites, not just the main site - -**Multisite cron log example:** - -``` -2025-11-28T02:30:01 ubuntu CRON[93961]: (web) CMD (cd /srv/www/demo.example.com/current && (wp site list --field=url | xargs -n1 -I % wp --url=% cron event run --due-now) > /dev/null 2>&1) -``` - -## Verification - -### Check if WP-Cron is Disabled - -```bash -# SSH into server -ssh admin@your.server.ip - -# Check WordPress configuration -cd /srv/www/example.com/current -grep -i "DISABLE_WP_CRON" .env - -# Should show: -# DISABLE_WP_CRON=true -``` - -### Check System Cron Configuration - -```bash -# View the cron job -cat /etc/cron.d/wordpress-example_com - -# Should show something like: -#Ansible: example.com WordPress cron -*/15 * * * * web cd /srv/www/example.com/current && wp cron event run --due-now > /dev/null 2>&1 -``` - -### Verify Cron is Running - -```bash -# Check system cron logs -sudo grep -i cron /var/log/syslog | tail -20 - -# Or on systems using journalctl -sudo journalctl -u cron | tail -20 - -# Test manually running the cron command -sudo -u web bash -c "cd /srv/www/example.com/current && wp cron event run --due-now" -``` - -**Example of successful cron execution in logs:** - -``` -2025-11-28T02:15:01 ubuntu CRON[93164]: (web) CMD (cd /srv/www/example.com/current && wp cron event run --due-now > /dev/null 2>&1) -2025-11-28T02:30:01 ubuntu CRON[93960]: (web) CMD (cd /srv/www/example.com/current && wp cron event run --due-now > /dev/null 2>&1) -2025-11-28T02:45:01 ubuntu CRON[94288]: (web) CMD (cd /srv/www/example.com/current && wp cron event run --due-now > /dev/null 2>&1) -``` - -If you see entries like these running every 15 minutes, your WordPress cron is working correctly. - -**Filter logs for a specific site:** - -```bash -# Check only cron logs for a specific site -sudo grep -i cron /var/log/syslog | grep "example.com" | tail -20 - -# Check cron logs for all sites -sudo grep -i cron /var/log/syslog | grep "(web) CMD" | tail -20 - -# Watch cron execution in real-time -sudo tail -f /var/log/syslog | grep -i cron -``` - -### List Scheduled WordPress Events - -```bash -# SSH into server -cd /srv/www/example.com/current - -# List all scheduled events -wp cron event list - -# Show events grouped by schedule -wp cron event list --format=table - -# Check when next events are due -wp cron event list --fields=hook,next_run_relative -``` - -## Common Cron Schedules - -WordPress uses these default schedules: - -- `hourly` - Once per hour -- `twicedaily` - Twice per day (12-hour intervals) -- `daily` - Once per day - -Custom schedules can be added by plugins. - -## Troubleshooting - -### Issue: Scheduled Posts Not Publishing - -**Symptoms:** Posts scheduled to publish remain in "Scheduled" status - -**Solutions:** - -```bash -# 1. Check if cron is running -sudo -u web bash -c "cd /srv/www/example.com/current && wp cron event run --due-now" - -# 2. List scheduled publish events -wp cron event list | grep publish - -# 3. Manually trigger the missed schedule check -wp cron event run --due-now - -# 4. Check server timezone matches WordPress timezone -date -wp option get timezone_string - -# 5. Check system cron is running -sudo systemctl status cron -``` - -### Issue: Plugin-Specific Scheduled Tasks Not Running - -**Symptoms:** Backup plugins, cache clearing, or other scheduled tasks don't execute - -**Solutions:** - -```bash -# 1. List all scheduled events -wp cron event list - -# 2. Check if the specific event exists -wp cron event list | grep plugin-name - -# 3. Manually trigger the event -wp cron event run plugin_hook_name - -# 4. Check plugin documentation for required WP-Cron support -# Some plugins may need wp-cron.php direct access - -# 5. If plugin requires wp-cron.php access, add Nginx location block -# See "Alternative: Direct wp-cron.php Access" below -``` - -### Issue: Too Many Cron Events Running - -**Symptoms:** High server load at cron execution times - -**Solutions:** - -```bash -# 1. List all events to identify heavy tasks -wp cron event list --format=csv > cron-events.csv - -# 2. Identify duplicate or unnecessary events -wp cron event list | sort | uniq -c - -# 3. Delete problematic events -wp cron event delete plugin_hook_name - -# 4. Adjust cron frequency if needed (see "Customization" below) -``` - -## Customization - -### Change Cron Frequency - -The default is every 15 minutes (`*/15`). To change: - -**Option 1: Set it per site in Trellis (Recommended)** - -In `trellis/group_vars//wordpress_sites.yml`: - -```yaml -wordpress_sites: - example.com: - cron_interval: '*/5' # single site, default '*/15' -``` - -For a multisite network the key is `cron_interval_multisite` (default `*/30`). -A network can also skip the generated job with -`multisite: { enabled: true, cron: false }`. - -Then re-provision: - -```bash -trellis provision --tags wordpress-setup production -``` - -Check `/etc/cron.d/` on the server afterwards to confirm the change. - -**Option 2: Manual Edit (Not Recommended)** - -```bash -# SSH into server -ssh admin@server.ip - -# Edit cron file -sudo nano /etc/cron.d/wordpress-example_com - -# Change schedule (e.g., every 5 minutes) -*/5 * * * * web cd /srv/www/example.com/current && wp cron event run --due-now > /dev/null 2>&1 - -# Cron will automatically reload changes -``` - -**Cron schedule examples:** -- `*/5 * * * *` - Every 5 minutes -- `*/10 * * * *` - Every 10 minutes -- `*/15 * * * *` - Every 15 minutes (default) -- `*/30 * * * *` - Every 30 minutes -- `0 * * * *` - Every hour (at :00) - -### Add Email Notifications for Errors - -By default, output is sent to `/dev/null`. To receive emails on errors: - -```bash -# Edit cron file -sudo nano /etc/cron.d/wordpress-example_com - -# Remove the redirect to capture errors -*/15 * * * * web cd /srv/www/example.com/current && wp cron event run --due-now 2>&1 - -# Or send to specific email -*/15 * * * * web cd /srv/www/example.com/current && wp cron event run --due-now 2>&1 | mail -s "WP Cron" admin@example.com -``` - -**Note:** Make sure your server has a mail transport agent (MTA) configured. - -### Run Specific Events More Frequently - -If you need certain events to run more often than every 15 minutes: - -```bash -# Add additional cron entries for specific hooks -# Example: Run backups every hour - -# Edit cron file -sudo nano /etc/cron.d/wordpress-example_com - -# Add line: -0 * * * * web cd /srv/www/example.com/current && wp cron event run backup_hook --due-now > /dev/null 2>&1 -``` - -## Alternative: Direct wp-cron.php Access - -Some legacy plugins may require direct access to `wp-cron.php`. While not recommended, you can enable this: - -**Add an Nginx location block** to the site template, `trellis/roles/wordpress-setup/templates/wordpress-site.conf.j2`: - -```nginx -# Allow direct wp-cron.php access (only if needed by legacy plugins) -location = /wp/wp-cron.php { - include fastcgi_params; - fastcgi_pass $upstream; - fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; - fastcgi_param DOCUMENT_ROOT $realpath_root; -} -``` - -Then re-provision. The site template belongs to the `wordpress-setup` role, so -`--tags nginx` would not deploy it: - -```bash -trellis provision production --tags wordpress-setup -``` - -**Warning:** This re-enables the WP-Cron problems mentioned above. Only use if absolutely necessary. - -## Migration Considerations - -When migrating from traditional WordPress hosting to Trellis: - -### Before Migration - -On your old hosting, if you had custom cron jobs in cPanel or similar: - -1. Document all custom cron jobs -2. Note their schedules and commands -3. Identify if they're WordPress-related or server tasks - -### After Migration - -1. **WordPress cron events are automatically preserved** - They're stored in the database, so they migrate with your data -2. **System-level cron jobs need to be recreated** - Add them to `/etc/cron.d/` or use Trellis configuration - -### Testing After Migration - -```bash -# 1. Verify WP-Cron is disabled -grep DISABLE_WP_CRON /srv/www/example.com/current/.env - -# 2. Check system cron exists -cat /etc/cron.d/wordpress-example_com - -# 3. List WordPress scheduled events -wp cron event list - -# 4. Manually run cron to test -sudo -u web bash -c "cd /srv/www/example.com/current && wp cron event run --due-now" - -# 5. Check for errors -tail -f /var/log/syslog | grep -i cron -``` - -## Best Practices - -1. **Keep default 15-minute interval** - It's a good balance between responsiveness and server load -2. **Monitor cron execution** - Set up alerts for failed cron jobs -3. **Don't rely on WP-Cron for critical tasks** - Use system cron or external monitoring for mission-critical tasks -4. **Test after major updates** - Verify cron still works after WordPress core or plugin updates -5. **Document custom schedules** - If you add custom cron frequencies, document them in your project README - -## Additional Resources - -- [WP-CLI Cron Commands](https://developer.wordpress.org/cli/commands/cron/) -- [WordPress Action Scheduler](https://actionscheduler.org/) - Alternative to WP-Cron for plugins -- [Crontab Guru](https://crontab.guru/) - Cron schedule expression generator -- [Trellis WordPress Setup](https://github.com/roots/trellis/tree/master/roles/wordpress-setup) - -## Related Documentation - -- [Provisioning Guide](README.md) - Trellis provisioning commands -- [Migration guide](https://wpvilla.in/migrate-wordpress-to-trellis-bedrock-step-by-step/) - Migrating from traditional WordPress -- [Deployment](https://roots.io/trellis/docs/deployments/) - Trellis deployment process diff --git a/trellis/provision/NEW-MACHINE.md b/trellis/provision/NEW-MACHINE.md deleted file mode 100644 index d229a08..0000000 --- a/trellis/provision/NEW-MACHINE.md +++ /dev/null @@ -1,317 +0,0 @@ -# New Machine Setup for Trellis Development - -Complete guide for setting up a Mac for [Roots Trellis](https://roots.io/trellis/) WordPress development. - -**Purpose:** This guide covers installing the tools and understanding the architecture needed for Trellis development on macOS. For setting up an existing Trellis project after your machine is configured, see [PROJECT-SETUP.md](PROJECT-SETUP.md). - -## Table of Contents - -- [Understanding Trellis Architecture](#understanding-trellis-architecture) -- [Required Tools Installation](#required-tools-installation) -- [SSH Key Setup](#ssh-key-setup) -- [Verification](#verification) -- [Next Steps](#next-steps) - -## Understanding Trellis Architecture - -### The Two Environments - -**Important distinction:** - -- **Host Machine (macOS):** Your local Mac where you edit code and run development tools -- **Trellis VM (Lima/Ubuntu):** Virtual machine that runs the WordPress LEMP stack - -### What Runs Where - -| Tool | Host Machine | Trellis VM | Purpose | -|------|-------------|------------|---------| -| Trellis CLI | ✅ Required | ❌ | Manages the VM | -| Composer | ✅ Required | ✅ Included | Installs PHP dependencies locally | -| PHP | ✅ Required | ✅ Included | Runs Composer on host; runs WordPress in VM | -| Node.js/npm | ✅ Required | ❌ | Runs Vite dev server on host | -| pnpm | ✅ Optional | ❌ | Faster npm alternative for host | -| MySQL/MariaDB | ❌ Conflicts! | ✅ Included | WordPress database in VM only | -| Nginx | ❌ Conflicts! | ✅ Included | Web server in VM only | -| PHP-FPM | ❌ Conflicts! | ✅ Included | WordPress PHP runtime in VM only | -| WP-CLI | ❌ Optional | ✅ Included | WordPress CLI (run via `trellis vm shell`) | - -### Key Points - -- **Host tools** are for development workflow (building assets, installing dependencies) -- **VM tools** are for running WordPress (web server, database, PHP runtime) -- Files are synced bidirectionally between host and VM via Lima -- You edit code on your host Mac, but WordPress runs inside the VM - -### Compatibility Note: Laravel Valet Users - -If you use Laravel Valet, you already have PHP/Composer/MySQL on your host: -- This is fine! Trellis VM uses its own isolated environment -- No need to reinstall PHP/Composer - your existing versions work -- Just be aware that local MySQL on port 3306 may conflict with some Ansible commands -- Solution: Run WP-CLI commands inside the VM via `trellis vm shell` - -## Required Tools Installation - -Install these tools on your Mac via Homebrew: - -```bash -# Install Homebrew (if not already installed) -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - -# Install Trellis CLI (required - manages the VM) -brew install roots/tap/trellis-cli - -# Install Composer (required - installs PHP dependencies) -brew install composer - -# Install PHP (required - runs Composer) -brew install php - -# Install Node.js (required - runs Vite dev server for theme assets) -# Option 1: Via fnm (Fast Node Manager, recommended) -brew install fnm -fnm install 24 # Install Node.js 24 LTS -fnm use 24 - -# Option 2: Direct installation via Homebrew -# brew install node - -# Install pnpm (optional but recommended - faster npm alternative) -npm install -g pnpm -``` - -### Notes for Laravel Valet Users - -- You likely already have PHP, Composer, and MySQL installed -- No need to reinstall - your existing versions work fine -- Trellis VM runs its own isolated LEMP stack -- Only potential conflict: Local MySQL on port 3306 (see Troubleshooting section) - -## SSH Key Setup - -### Generate SSH Key - -If you don't already have an SSH key: - -```bash -# Generate new SSH key (use your email) -ssh-keygen -t ed25519 -C "your.email@example.com" - -# Add to ssh-agent -eval "$(ssh-agent -s)" -ssh-add ~/.ssh/id_ed25519 - -# Copy public key to clipboard -cat ~/.ssh/id_ed25519.pub | pbcopy -``` - -### Add to GitHub - -1. Go to https://github.com/settings/keys -2. Click "New SSH key" -3. Paste your public key -4. Test: `ssh -T git@github.com` - -### Add to Production Server (Optional) - -This step can be done later when you need production access. See the project-specific setup guide for details on adding your key to production servers. - -## Verification - -Check that all tools are installed correctly: - -```bash -trellis --version # Should show 1.17.0+ -composer --version # Should show 2.9.0+ -php --version # Should show 8.3.0+ -node --version # Should show v24.0.0+ -npm --version # Should show 11.0.0+ -pnpm --version # Should show 10.0.0+ (if installed) -ssh -T git@github.com # Should show successful GitHub authentication -``` - -## How Trellis Development Works - -### Development Workflow Architecture - -``` -┌─────────────────────────────────────────────────────────────┐ -│ HOST MACHINE (macOS) │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ Your Code Editor (VS Code, PHPStorm, etc.) │ -│ ↓ │ -│ ~/code/your-project/ │ -│ ├── site/ │ -│ │ ├── composer.json ← Composer installs here │ -│ │ └── web/app/themes/your-theme/ │ -│ │ ├── package.json ← npm/pnpm installs here │ -│ │ ├── resources/ ← You edit CSS/JS here │ -│ │ └── public/ ← Vite builds assets here │ -│ └── trellis/ ← Trellis CLI runs here │ -│ │ -│ Terminal Commands: │ -│ • npm run dev (Vite dev server, HMR) │ -│ • composer install (Install PHP dependencies) │ -│ • trellis vm start (Start VM) │ -│ • trellis provision (Provision VM) │ -│ │ -└─────────────────────────────────────────────────────────────┘ - ↕ ↕ ↕ - Lima syncs files bidirectionally - ↕ ↕ ↕ -┌─────────────────────────────────────────────────────────────┐ -│ TRELLIS VM (Lima/Ubuntu) │ -├─────────────────────────────────────────────────────────────┤ -│ │ -│ /srv/www/your-project.test/current/ ← Synced from host │ -│ │ -│ LEMP Stack (runs WordPress): │ -│ • Nginx (port 80/443) → Web server │ -│ • PHP-FPM 8.3 → Executes WordPress PHP │ -│ • MySQL 8.0 → WordPress database │ -│ • WP-CLI → WordPress management │ -│ │ -│ Access via: │ -│ • trellis vm shell (Interactive shell) │ -│ • https://your-project.test (Web browser) │ -│ │ -└─────────────────────────────────────────────────────────────┘ -``` - -### Why Two Environments? - -**Host Machine handles:** -- **Code editing:** You edit files on your Mac with your preferred editor -- **Asset building:** Vite compiles CSS/JS with HMR for instant feedback -- **Dependency management:** Composer and npm download packages locally -- **Version control:** Git operations happen on your Mac - -**Trellis VM handles:** -- **WordPress runtime:** Nginx serves PHP files through PHP-FPM -- **Database:** MySQL stores WordPress content -- **WordPress core:** All WordPress PHP execution happens here -- **Production parity:** VM matches production server configuration - -**Benefits:** -- **Isolated environment:** VM can't conflict with your Laravel Valet setup -- **Production parity:** VM matches production Ubuntu/Nginx/PHP versions -- **Fast development:** Edit files on Mac, see changes instantly via file sync -- **No containers:** Lima is lighter than Docker, faster than Vagrant - -### Common Confusion: Do I Need Duplicate Tools? - -**No!** Here's why you need each tool on the host: - -- **Composer on host:** Downloads dependencies to `vendor/` which syncs to VM - - VM also has Composer, but you run it on host for speed - -- **Node.js on host:** Runs Vite dev server for HMR (hot reload) - - VM doesn't need Node.js - it just serves the compiled assets - -- **PHP on host:** Only needed to run Composer - - WordPress doesn't run on host PHP - it runs in VM's PHP-FPM - -- **No MySQL on host:** Would conflict with VM's MySQL on port 3306 - - If you have MySQL from Valet, stop it or run WP-CLI in VM - -**Real-world example:** -```bash -# On HOST: Install dependencies and build assets -cd ~/code/your-project/site/web/app/themes/your-theme -pnpm install # Host Node.js downloads packages -pnpm run dev # Host Node.js runs Vite dev server - -# Files auto-sync to VM via Lima -# WordPress in VM serves your site with the built assets - -# On VM: Run WordPress commands -trellis vm shell # Enter VM -wp cache flush # VM's WP-CLI talks to VM's MySQL -``` - -## Troubleshooting - -### Port 3306 Conflict (Local Database) - -**Symptom:** Ansible playbooks fail with SSH connection errors - -**Cause:** Local MariaDB/MySQL running on port 3306 conflicts with Trellis VM - -**Solution:** Run WP-CLI commands inside Trellis VM instead: - -```bash -# Instead of Ansible playbooks, use direct VM commands -trellis vm shell --workdir /srv/www/your-project.test/current - -# Now run WP-CLI commands -wp db export /tmp/backup.sql.gz --path=web/wp -wp cache flush --path=web/wp -``` - -### VM Won't Start - -**Symptom:** `trellis vm start` fails or hangs - -**Solution:** - -```bash -# Check Lima VM status -limactl list - -# Stop and delete VM -trellis vm delete - -# Start fresh -trellis vm start -trellis provision development -``` - -### Composer Memory Errors - -**Symptom:** `composer install` fails with "Allowed memory size exhausted" - -**Solution:** - -```bash -# Run Composer with unlimited memory -php -d memory_limit=-1 $(which composer) install -``` - -## Next Steps - -Now that your machine is set up for Trellis development: - -1. **Clone a Trellis project:** See [PROJECT-SETUP.md](PROJECT-SETUP.md) for setting up an existing project -2. **Start a new Trellis project:** Follow the [Trellis documentation](https://roots.io/trellis/docs/installation/) -3. **Learn Trellis workflows:** Review [README.md](README.md) in the provision directory for common commands - -## Resources - -- **Trellis Docs:** https://roots.io/trellis/docs/ -- **Trellis VM Docs:** https://roots.io/trellis/docs/trellis-vm/ -- **Bedrock Docs:** https://roots.io/bedrock/docs/ -- **Sage Docs:** https://roots.io/sage/docs/ - -## Quick Reference - -```bash -# VM Management -trellis vm start # Start the VM -trellis vm stop # Stop the VM -trellis vm shell # SSH into VM -trellis vm delete # Delete VM completely -limactl list # List all Lima VMs - -# Provisioning -trellis provision development # Provision development environment -trellis provision --tags nginx production # Provision specific tags - -# Deployment -trellis deploy staging # Deploy to staging -trellis deploy production # Deploy to production - -# WP-CLI via VM -trellis vm shell -- wp cli info --path=/srv/www/SITE/current/web/wp -trellis vm shell -- wp cache flush --path=/srv/www/SITE/current/web/wp -``` diff --git a/trellis/provision/PROJECT-SETUP.md b/trellis/provision/PROJECT-SETUP.md deleted file mode 100644 index 0ddf728..0000000 --- a/trellis/provision/PROJECT-SETUP.md +++ /dev/null @@ -1,915 +0,0 @@ -# Trellis Project Setup Guide - -Guide for cloning and setting up an existing Trellis/Bedrock WordPress project on a Mac. - -**Prerequisites:** Your machine must already be configured for Trellis development. If not, see [NEW-MACHINE.md](NEW-MACHINE.md) first. - -**Note**: Commands in this guide use `admin_user` as a placeholder for your Trellis admin username (configured in `group_vars/all/users.yml`). Replace `admin_user` with your actual configured username (e.g., `admin`, `deploy`, `warden`, your name, etc.). - -## Table of Contents - -- [Clone Repository](#clone-repository) -- [Install Dependencies](#install-dependencies) -- [Configure Environment Files](#configure-environment-files) -- [Start and Provision Trellis VM](#start-and-provision-trellis-vm) -- [Database and Files Setup](#database-and-files-setup) -- [Theme Development](#theme-development) -- [Production Access](#production-access) -- [Common Workflows](#common-workflows) -- [Troubleshooting](#troubleshooting) -- [Verification Checklist](#verification-checklist) - -## Clone Repository - -```bash -cd ~/code -git clone git@github.com:YOUR_ORG/your-project.git -cd your-project -``` - -**Repository structure** for Roots.io projects: -``` -your-project/ -├── site/ # Bedrock WordPress installation -│ ├── composer.json # PHP dependencies -│ ├── config/ # Environment configs -│ └── web/ -│ ├── app/ -│ │ └── themes/your-theme/ # Sage theme -│ └── wp/ # WordPress core (managed by Composer) -└── trellis/ # Server provisioning and deployment - ├── group_vars/ # Ansible configuration - └── trellis.yml # Trellis configuration -``` - -## Install Dependencies - -### 1. Install PHP Dependencies (Bedrock) - -Before running `composer install`, check if your project requires any special authentication (e.g., for premium plugins). - -#### Example: ACF Pro Authentication - -If your project uses Advanced Custom Fields Pro: - -```bash -cd site - -# Create auth.json with ACF Pro license key -cat > auth.json << 'EOF' -{ - "http-basic": { - "connect.advancedcustomfields.com": { - "username": "YOUR_ACF_LICENSE_KEY", - "password": "http://YOUR_SITE_URL" - } - } -} -EOF -``` - -**Security note:** `auth.json` should be in `.gitignore` and never committed. - -#### Install Composer Packages - -```bash -# In site directory -composer install -``` - -**What this installs:** -- WordPress core -- WordPress plugins (via Composer) -- Premium plugins (if configured) -- Bedrock boilerplate dependencies - -**Output:** Creates `site/vendor/` directory (~100MB) - -### 2. Install Theme Dependencies - -```bash -cd web/app/themes/your-theme - -# Using pnpm (recommended) -pnpm install - -# OR using npm -npm install -``` - -**What this installs:** -- Vite (build tool) -- CSS framework (Tailwind, etc.) -- Theme framework dependencies (Sage, etc.) - -**Output:** Creates `node_modules/` directory (~400MB) - -## Configure Environment Files - -### Development Environment (.env) - -Create `.env` file in `site/` directory: - -```bash -cd site -cp .env.example .env -``` - -Edit `.env` with your local development settings: - -```env -DB_NAME='your_project_dev' -DB_USER='example_dbuser' -DB_PASSWORD='example_dbpassword' - -# Optional: WordPress admin user (created during provisioning) -WP_ENV='development' -WP_HOME='http://yourproject.test' -WP_SITEURL="${WP_HOME}/wp" - -# Generate salts at: https://roots.io/salts.html -AUTH_KEY='generateme' -SECURE_AUTH_KEY='generateme' -# ... (other salts) -``` - -### Trellis Configuration - -Check `trellis/group_vars/development/wordpress_sites.yml`: - -```yaml -wordpress_sites: - yourproject.test: - site_hosts: - - canonical: yourproject.test - local_path: ../site # Path to Bedrock installation - admin_email: admin@yourproject.test - multisite: - enabled: false - ssl: - enabled: true - provider: self-signed - cache: - enabled: false -``` - -**Note:** Most projects have this pre-configured. Only edit if customizing your local setup. - -## Start and Provision Trellis VM - -### 1. Initialize Trellis - -**IMPORTANT:** Run this before starting the VM for the first time. - -```bash -cd trellis -trellis init -``` - -**What this does:** -- Creates Python virtual environment (`.trellis/virtualenv/`) -- Installs Ansible and dependencies -- Prepares project for Trellis CLI management - -**First-time setup:** ~2-5 minutes (downloading and installing Python packages) - -**Expected output:** -``` -Initializing project... - -[✓] Created virtualenv (/path/to/project/trellis/.trellis/virtualenv) -[✓] Ensure pip is up to date -[✓] Dependencies installed -``` - -**Note:** You may see verbose pip output if installation takes longer than expected. This is normal. - -### 2. Copy Vault Password - -**IMPORTANT:** Required for provisioning. The vault password decrypts sensitive configuration (database passwords, etc.). - -If you're setting up an existing project on a new machine, copy the `.vault_pass` file from your existing development machine: - -```bash -# On your existing machine -cat /path/to/project/trellis/.vault_pass - -# On your new machine -cd /Users/j/code/example.com/trellis -echo "PASTE_PASSWORD_HERE" > .vault_pass -chmod 600 .vault_pass -``` - -**Security notes:** -- `.vault_pass` should be in `.gitignore` (never commit it!) -- Each team member needs this file for provisioning -- Share securely (1Password, encrypted message, etc.) - -**Alternative (new projects only):** If starting fresh, you can create a new vault password: -```bash -echo "$(openssl rand -base64 32)" > trellis/.vault_pass -chmod 600 trellis/.vault_pass -``` -Then you'll need to re-encrypt vault files with the new password. - -### 3. Start Trellis VM - -```bash -cd trellis -trellis vm start -``` - -**What this does:** -- Creates a Lima VM with Ubuntu 24.04 -- Mounts project directory to VM -- Sets up bidirectional file sync -- Automatically adds site hosts to `/etc/hosts` - -**First-time setup:** ~2-5 minutes - -**Expected output:** -``` -Starting VM... -VM started successfully. -VM IP: 192.168.56.5 -``` - -### 4. Verify /etc/hosts Entry - -Trellis CLI automatically adds your site to `/etc/hosts`: - -```bash -grep yourproject.test /etc/hosts -``` - -**Expected output:** `192.168.56.5 yourproject.test` - -**If missing:** Add manually: -```bash -sudo sh -c 'echo "192.168.56.5 yourproject.test" >> /etc/hosts' -``` - -### 5. Provision Development Environment - -```bash -# In trellis directory -trellis provision development -``` - -**What this does:** -- Installs LEMP stack (Linux, Nginx, MySQL, PHP) -- Configures Nginx virtual hosts -- Sets up PHP-FPM -- Creates MySQL database -- Installs WordPress via WP-CLI -- Configures SSL certificates (self-signed for local) - -**First-time provisioning:** ~10-15 minutes - -**Expected output:** -``` -PLAY RECAP *************************************************************** -192.168.56.5 : ok=XXX changed=YYY unreachable=0 failed=0 skipped=ZZZ -``` - -### 6. Access Your Site - -**For HTTP setup (recommended for local development):** - -Visit `http://yourproject.test` in your browser. The site should load without any security warnings. - -**For HTTPS setup with self-signed certificate:** - -If you configured `ssl: enabled: true` in `wordpress_sites.yml`, visit `https://yourproject.test`. You'll see a security warning (expected for self-signed certificates). - -**Safari:** -1. Click "Show Details" → "visit this website" -2. Enter macOS password to trust certificate - -**Chrome:** -1. Click "Advanced" → "Proceed to yourproject.test (unsafe)" -2. Or type `thisisunsafe` anywhere on the warning page - -## Database and Files Setup - -Choose one of these options: - -### Option 1: Fresh WordPress Installation - -If you just provisioned for the first time, you already have a fresh WordPress installation. - -**Access WordPress:** -- URL: `http://yourproject.test/wp/wp-admin/` (or https if you enabled SSL) -- Username: `admin` (or as configured in `wordpress_sites.yml`) -- Password: `admin` (or as configured) - -**Configure site:** -1. Log in to WordPress admin -2. Activate your theme (Appearance → Themes) -3. Configure settings as needed - -### Option 2: Pull from Production (Recommended) - -Pull production database and uploads to get real content. - -#### Pull Database - -**Method 1: Ansible Playbook** - -```bash -cd trellis - -# Backup development database first (optional but recommended) -ansible-playbook database-backup.yml -e env=development -e site=yourproject.com - -# Pull from production to development -ansible-playbook database-pull.yml -e env=production -e site=yourproject.com -``` - -**Note:** This requires the `database-pull.yml` playbook in your Trellis directory. If not present, copy from [wp-ops/trellis/backup/](../backup/). - -**Method 2: Direct VM Commands** - -If Ansible playbooks fail (e.g., port 3306 conflicts): - -```bash -trellis vm shell --workdir /srv/www/yourproject.com/current -- bash -c " -echo '=== Backing up current development database ===' -wp db export /tmp/dev_backup_\$(date +%Y%m%d_%H%M%S).sql.gz --path=web/wp - -echo '' -echo '=== Pulling production database dump ===' -ssh -o StrictHostKeyChecking=no web@yourproject.com 'cd /srv/www/yourproject.com/current && wp db export - --path=web/wp' | gzip > /tmp/prod_import.sql.gz - -echo '' -echo '=== Importing production database to development ===' -gunzip < /tmp/prod_import.sql.gz | wp db import - --path=web/wp - -echo '' -echo '=== Running search-replace for URLs ===' -wp search-replace 'https://yourproject.com' 'http://yourproject.test' --all-tables --precise --path=web/wp - -echo '' -echo '=== Flushing cache ===' -wp cache flush --path=web/wp - -echo '' -echo '=== Database pull complete! ===' -" -``` - -**Requirements:** -- SSH key added to production server -- Production access configured - -**URL Search-Replace Notes:** -- The example above converts `https://yourproject.com` → `http://yourproject.test` -- Adjust based on your local configuration: - - If your local uses HTTPS (self-signed cert): `https://yourproject.com` → `https://yourproject.test` - - If your local uses HTTP: `https://yourproject.com` → `http://yourproject.test` -- Check your `site/.env` file for `WP_HOME` value to confirm local URL scheme - -**For Multisite Networks:** - -If your project uses WordPress multisite, you need additional URL updates. **IMPORTANT**: Use WP-CLI's `wp search-replace --network` to ensure URLs are updated in all subsites' content, not just the database tables. - -```bash -# After importing the database, update multisite URLs using WP-CLI -trellis vm shell --workdir /srv/www/yourproject.com/current -- bash -c " -echo '=== Running search-replace for all subsites ===' -wp search-replace 'yourproject.com' 'yourproject.test' --network --path=web/wp - -echo '' -echo '=== Converting HTTPS to HTTP (if needed) ===' -wp search-replace 'https://yourproject.test' 'http://yourproject.test' --network --path=web/wp - -echo '' -echo '=== Verifying all subsites ===' -wp site list --path=web/wp - -echo '' -echo '=== Flushing cache ===' -wp cache flush --network --path=web/wp -" -``` - -**Why use `wp search-replace --network`?** -- Updates URLs in post content, options, and metadata across all subsites -- The `--network` flag ensures all subsites are processed -- MySQL `UPDATE` commands only change table values, not serialized data in content -- Without this, subsites may redirect to production URLs - -**Alternative (MySQL only - NOT RECOMMENDED):** - -If WP-CLI is unavailable, you can use MySQL directly, but this won't update URLs inside post content: - -```bash -trellis vm shell -- bash -c " -mysql -u dbuser -p'dbpassword' dbname -e \" -UPDATE wp_sitemeta SET meta_value = 'http://yourproject.test' WHERE meta_key = 'siteurl'; -UPDATE wp_blogs SET domain = REPLACE(domain, 'yourproject.com', 'yourproject.test'); -\" -" -``` - -Replace `dbuser`, `dbpassword`, and `dbname` with values from your `site/.env` file. - -#### Pull Uploads - -**Method 1: Ansible Playbook (Recommended)** - -```bash -cd trellis - -# Pull uploads from production to development -ansible-playbook files-pull.yml -e env=production -e site=yourproject.com -``` - -**What this does:** -- Syncs `/srv/www/yourproject.com/shared/uploads/` from production -- Uses rsync (incremental transfers) -- Time varies based on upload size (~5-10 minutes typical) - -**Method 2: Direct rsync (If Ansible Fails)** - -If Ansible playbooks fail due to port conflicts: - -```bash -# Add production server to known hosts (if needed) -ssh-keyscan -H yourproject.com >> ~/.ssh/known_hosts - -# Sync uploads directly -rsync -avz --progress web@yourproject.com:/srv/www/yourproject.com/shared/uploads/ /Users/j/code/yourproject/site/web/app/uploads/ -``` - -**Note:** Lima VM provides automatic bidirectional file sync, so uploads synced to your local machine are immediately available in the VM. - -#### Setup Theme After Database Pull - -**CRITICAL:** After pulling the production database, you must install theme dependencies and build assets, or your site will show errors (typically 500 Internal Server Error). - -For **Sage themes** (most common): - -```bash -# Navigate to theme directory -cd site/web/app/themes/your-theme - -# Install Composer dependencies (Sage/Acorn) -composer install - -# Install NPM dependencies -npm install -# OR if using pnpm: pnpm install - -# Build theme assets -npm run build -# OR if using pnpm: pnpm build -``` - -**Why this is required:** -- Sage themes use Acorn (Laravel for WordPress) which requires Composer autoloader -- Without `composer install`, WordPress cannot load the theme (500 error) -- Without `npm run build`, CSS/JS assets won't be compiled -- Production database references built assets that don't exist locally yet - -**Verification:** - -After setup, your site should load without errors: - -```bash -# Test site accessibility -curl -I http://yourproject.test - -# Expected: HTTP/1.1 200 OK -# If you see 500 error, check theme dependencies above -``` - -## Theme Development - -### Start Development Server - -```bash -cd site/web/app/themes/your-theme - -# Using pnpm -pnpm dev - -# OR using npm -npm run dev -``` - -**What this does:** -- Starts Vite dev server with HMR (Hot Module Replacement) -- Watches for file changes in `resources/` -- Auto-reloads browser on changes -- Proxies requests to your local site - -**Expected output:** -``` -VITE v5.x.x ready in XXX ms - -➜ Local: http://localhost:3000/ -➜ Network: use --host to expose -``` - -**Access:** -- **With HMR:** `http://localhost:3000` (recommended for development) -- **Direct:** `http://yourproject.test` (or https if you enabled SSL) - -### Build for Production - -Before deploying to staging/production: - -```bash -cd site/web/app/themes/your-theme - -# Using pnpm -pnpm build - -# OR using npm -npm run build -``` - -**What this does:** -- Compiles and minifies CSS/JS -- Generates `public/build/` directory with versioned assets -- Optimizes for production - -## Production Access - -**Note:** Only needed when deploying or accessing production server. - -### Add SSH Key to Production - -When setting up a new machine, you need to add your SSH key to the production server. - -#### Prerequisites - -1. **Add your SSH key to GitHub:** - ```bash - # Display your public key - cat ~/.ssh/id_ed25519.pub - - # Add it to GitHub: https://github.com/settings/keys - ``` - -2. **Verify your key is in the Trellis users configuration:** - - Check `trellis/group_vars/all/users.yml` includes your GitHub username: - ```yaml - users: - - name: "{{ web_user }}" - keys: - - https://github.com/YOUR_USERNAME.keys - ``` - -#### Provision SSH Keys to Production - -**IMPORTANT:** This step requires someone with existing production access. - -From a machine that already has SSH access to production: - -```bash -cd /path/to/yourproject/trellis - -# Provision users (updates authorized_keys from GitHub) -trellis provision --tags users production -``` - -**What this does:** -- Fetches SSH keys from GitHub URLs configured in `users.yml` -- Updates `/home/web/.ssh/authorized_keys` (for web user) -- Updates `/home/admin_user/.ssh/authorized_keys` (for admin user) -- **Does NOT update** `/root/.ssh/authorized_keys` (root SSH disabled for security) - -**Expected output:** -``` -PLAY RECAP *************************************************************** -yourproject.com : ok=XX changed=X unreachable=0 failed=0 -``` - -**Time:** ~30 seconds to 2 minutes - -#### Verify Production Access - -From your new machine: - -```bash -# Test SSH connection as web user -ssh web@yourproject.com - -# Should get shell access -# If successful: web@yourproject:~$ - -# Test SSH connection as admin user -ssh admin_user@yourproject.com - -# Should get shell access -# If successful: admin_user@yourproject:~$ -``` - -**Note:** Root SSH access is disabled for security. Use your configured admin user for sudo access. - -#### Speed Up SSH with Connection Multiplexing (Recommended) - -If you SSH into production frequently (log checks, WP-CLI, fail2ban lookups, deploys), add connection multiplexing to `~/.ssh/config` so repeat connections reuse an already-authenticated socket instead of renegotiating SSH each time: - -``` -Host yourproject.com - KexAlgorithms curve25519-sha256@libssh.org - ControlMaster auto - ControlPath ~/.ssh/sockets/%r@%h-%p - ControlPersist 600 -``` - -```bash -mkdir -p ~/.ssh/sockets && chmod 700 ~/.ssh/sockets -``` - -**Notes:** -- Multiplexing is keyed per remote user (`%r`), so `web@yourproject.com` and `admin_user@yourproject.com` get separate sockets — both benefit independently. -- `ControlPersist 600` keeps the master connection open for 10 minutes after your last session closes, so a burst of commands (e.g. diagnostics during an incident) only pays the handshake cost once. -- Verify it's working: run the same SSH command twice in a row — the second should return in well under a second, and `~/.ssh/sockets/` will contain a socket file per user. - -#### Troubleshooting - -**Problem:** `Permission denied (publickey)` after provisioning - -**Solutions:** -1. Verify your key is on GitHub: `curl https://github.com/YOUR_USERNAME.keys` -2. Wait 1-2 minutes for GitHub to update its cache -3. Re-run provisioning: `trellis provision --tags users production` -4. Check if key was added: `ssh admin_user@yourproject.com "cat /home/web/.ssh/authorized_keys"` - -### Deploy to Production - -```bash -cd trellis -trellis deploy production -``` - -**What this does:** -- Pulls latest code from configured branch (usually `main`) -- Runs `composer install --no-dev --optimize-autoloader` -- Runs theme build process -- Activates new release -- Keeps previous releases for rollback - -## Common Workflows - -### Daily Development - -```bash -# Start VM (if not running) -cd trellis && trellis vm start - -# Start theme dev server (in another terminal) -cd site/web/app/themes/your-theme && pnpm dev - -# Visit http://localhost:3000 for HMR -``` - -### Stop VM (Save Resources) - -```bash -cd trellis -trellis vm stop -``` - -### Delete VM (Fresh Start) - -```bash -cd trellis -trellis vm delete - -# Then re-provision -trellis vm start -trellis provision development -``` - -### Run WP-CLI Commands - -```bash -# From host machine -trellis vm shell -- wp cache flush --path=/srv/www/yourproject.com/current/web/wp -trellis vm shell -- wp plugin list --path=/srv/www/yourproject.com/current/web/wp - -# OR enter VM interactively -trellis vm shell --workdir /srv/www/yourproject.com/current -# Now run: wp cache flush --path=web/wp -``` - -## Troubleshooting - -### File Changes Not Appearing - -**Symptom:** Code changes don't appear in browser - -**Cause:** Usually WordPress cache, not file sync - -**Solution:** -```bash -# Flush WordPress cache -trellis vm shell -- wp cache flush --path=/srv/www/yourproject.com/current/web/wp - -# Hard refresh browser (Cmd+Shift+R) - -# For CSS/JS changes, restart Vite -cd site/web/app/themes/your-theme && pnpm dev -``` - -### Port 3306 Conflict - -**Symptom:** Ansible playbooks fail with SSH errors - -**Cause:** Local MariaDB/MySQL conflicts with Trellis VM - -**Solution:** Run WP-CLI commands inside VM: -```bash -trellis vm shell --workdir /srv/www/yourproject.com/current -wp db export /tmp/backup.sql.gz --path=web/wp -``` - -### SSL Certificate Warning - -**Symptom:** Browser shows "Your connection is not private" - -**Cause:** Self-signed certificate for local development - -**Solution:** -- Click "Advanced" → "Proceed" (safe for local dev) -- Or type `thisisunsafe` on warning page (Chrome) - -### VM Won't Start - -**Symptom:** `trellis vm start` fails or hangs - -**Solution:** -```bash -# Check Lima VM status -limactl list - -# Delete and recreate VM -trellis vm delete -trellis vm start -trellis provision development -``` - -### Composer Memory Errors - -**Symptom:** `composer install` fails with memory error - -**Solution:** -```bash -php -d memory_limit=-1 $(which composer) install -``` - -### 500 Internal Server Error After Database Pull - -**Symptom:** Site shows 500 error after pulling production database - -**Cause:** Missing theme dependencies (Composer/NPM) or unbuilt assets - -**Solution:** -```bash -cd site/web/app/themes/your-theme - -# Install and build theme -composer install -npm install -npm run build - -# Test site -curl -I http://yourproject.test -``` - -### WP-CLI "Error locating autoloader" - -**Symptom:** WP-CLI commands fail with "Error locating autoloader. Please run `composer install`" - -**Cause:** Theme Composer dependencies not installed, or running from wrong directory - -**Solution:** -```bash -# Install theme Composer dependencies -cd site/web/app/themes/your-theme -composer install - -# Alternative: Update URLs directly via MySQL -trellis vm shell -- bash -c " -mysql -u dbuser -p'dbpassword' dbname -e \" -UPDATE wp_options SET option_value = 'http://yourproject.test/wp' WHERE option_name = 'siteurl'; -UPDATE wp_options SET option_value = 'http://yourproject.test' WHERE option_name = 'home'; -SELECT option_name, option_value FROM wp_options WHERE option_name IN ('siteurl', 'home'); -\" -" -``` - -Replace `dbuser`, `dbpassword`, and `dbname` with values from your `site/.env` file. - -### SSH Host Key Verification Failed (File Sync) - -**Symptom:** `rsync` or `ansible-playbook files-pull.yml` fails with "Host key verification failed" - -**Cause:** Production server's SSH key not in your `~/.ssh/known_hosts` - -**Solution:** -```bash -# Add production server to known hosts -ssh-keyscan -H yourproject.com >> ~/.ssh/known_hosts - -# Retry the sync operation -rsync -avz web@yourproject.com:/srv/www/yourproject.com/shared/uploads/ /path/to/site/web/app/uploads/ -``` - -## Verification Checklist - -After setup, verify everything works: - -- [ ] Trellis VM running: `trellis vm status` -- [ ] Site accessible (200 OK): `curl -I http://yourproject.test` -- [ ] WordPress admin accessible: `http://yourproject.test/wp/wp-admin/` -- [ ] Bedrock Composer packages installed: `ls -la site/vendor/` -- [ ] Theme Composer packages installed: `ls -la site/web/app/themes/your-theme/vendor/` -- [ ] Theme NPM packages installed: `ls -la site/web/app/themes/your-theme/node_modules/` -- [ ] Theme assets built: `ls -la site/web/app/themes/your-theme/public/build/` -- [ ] Theme dev server works: Run dev server and visit `http://localhost:3000` -- [ ] HMR works: Edit CSS file and see instant changes -- [ ] WP-CLI works: `trellis vm shell -- wp cli info --path=/srv/www/yourproject.com/current/web/wp` -- [ ] Database accessible: `trellis vm shell -- wp db check --path=/srv/www/yourproject.com/current/web/wp` -- [ ] Uploads synced: Check `site/web/app/uploads/` has files from production - -## Next Steps - -1. **Familiarize with codebase:** - - Review theme documentation - - Understand project structure - - Check for project-specific CLAUDE.md or README.md - -2. **Configure IDE:** - - Install PHP CodeSniffer extension - - Configure ESLint and Prettier - - Set up framework-specific syntax highlighting - -3. **Review project workflows:** - - Check deployment process - - Understand branching strategy - - Review code standards - -## Resources - -- **Trellis Docs:** https://roots.io/trellis/docs/ -- **Bedrock Docs:** https://roots.io/bedrock/docs/ -- **Sage Docs:** https://roots.io/sage/docs/ -- **Trellis VM Docs:** https://roots.io/trellis/docs/trellis-vm/ -- **Trellis Tools (backup/migration):** [../../README.md](../../README.md) - -## Quick Reference - -```bash -# Initial Setup -trellis init # Initialize Trellis (run once) - -# VM Management -trellis vm start # Start VM -trellis vm stop # Stop VM -trellis vm shell # SSH into VM -trellis vm delete # Delete VM - -# Provisioning -trellis provision development # Provision development -trellis provision production # Provision production - -# Deployment -trellis deploy staging # Deploy to staging -trellis deploy production # Deploy to production - -# Database Operations (requires playbooks in trellis/) -ansible-playbook database-backup.yml -e env=production -e site=yourproject.com -ansible-playbook database-pull.yml -e env=production -e site=yourproject.com -ansible-playbook files-pull.yml -e env=production -e site=yourproject.com - -# Theme Setup (after database pull - REQUIRED for Sage themes) -cd site/web/app/themes/your-theme -composer install # Install Acorn/Sage dependencies -npm install # Install build dependencies -npm run build # Build theme assets - -# Theme Development -pnpm dev # Start dev server with HMR -pnpm build # Build for production - -# WP-CLI -trellis vm shell -- wp cache flush --path=/srv/www/yourproject.com/current/web/wp -trellis vm shell -- wp plugin list --path=/srv/www/yourproject.com/current/web/wp -``` - -## Project-Specific Notes - -**This is a template guide.** Your specific project may have: -- Additional dependencies or plugins requiring authentication -- Custom deployment workflows -- Specific multisite configuration -- Project-specific scripts or tools - -Check your project's `README.md` or `CLAUDE.md` for additional setup instructions. diff --git a/trellis/provision/README.md b/trellis/provision/README.md deleted file mode 100644 index 470f988..0000000 --- a/trellis/provision/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# Provisioning - -## Table of Contents - -### Setup Guides -- [New Machine Setup](NEW-MACHINE.md) - Configure Mac for Trellis development (install tools, understand architecture) -- [Project Setup](PROJECT-SETUP.md) - Clone and setup existing Trellis/Bedrock projects - -### Configuration Guides -- [WordPress Cron](CRON.md) - How Trellis handles WordPress cron with system cron - -### Command Reference -- [General Provisioning](#navigate-to-trellis-directory) - Common provisioning commands (below) - ---- - -## Quick Command Reference - -This section provides common Trellis provisioning and deployment commands. These are the day-to-day commands you'll use after your machine and project are set up. - -For initial setup, see the [Setup Guides](#setup-guides) above. - -## Navigate to trellis directory - -```bash -cd trellis -``` - -## Provision development environment - -```bash -ansible-playbook dev.yml -``` - -## Deploy to staging/production - -```bash -ansible-playbook deploy.yml -e env=staging -ansible-playbook deploy.yml -e env=production -``` - -## Re-provision production with specific tags - -Use `trellis provision` command instead of `ansible-playbook server.yml`: - -```bash -trellis provision --tags php,nginx,composer production -``` - -## Full server provisioning - -Use sparingly: - -```bash -trellis provision production -``` - -## PHP Version Upgrade Process - -1. Update `php_version` in `trellis/group_vars/all/main.yml` -2. Run with `php`, `nginx`, `wordpress-setup`, `users`, and `memcached` tags: - -```bash -trellis provision --tags php,nginx,wordpress-setup,users,memcached production -``` - -**Why these tags are required:** -- `php` - Installs new PHP version and extensions -- `nginx` - Updates Nginx configuration for new PHP-FPM socket -- `wordpress-setup` - Creates `/etc/php/X.X/fpm/pool.d/wordpress.conf` -- `users` - **Critical**: Regenerates sudoers with new PHP version for passwordless `php-fpm reload` -- `memcached` - Installs PHP version-specific memcached extension (e.g., `php8.3-memcached`) - -**Note:** Without the `users` tag, deployments will fail when trying to reload PHP-FPM because the sudoers configuration still references the old PHP version. - -## WordPress Cron - -Trellis automatically configures system cron instead of WordPress's built-in WP-Cron for more reliable scheduled task execution. - -For complete documentation on how WordPress cron works with Trellis, including: -- How system cron replaces WP-Cron -- Verification and troubleshooting -- Customization options -- Migration considerations - -See [CRON.md](CRON.md). diff --git a/trellis/security/README.md b/trellis/security/README.md index a4ce596..8086b95 100644 --- a/trellis/security/README.md +++ b/trellis/security/README.md @@ -543,7 +543,7 @@ deny 62.60.130.228; ### Trellis Operations - **[trellis/backup](../backup/)** - Database and file backups - **[trellis/monitoring](../monitoring/)** - Server monitoring tools -- **[trellis/provision](../provision/)** - Server provisioning guides +- **[Provisioning guides](https://wpvilla.in/trellis-provision-tags-php-version-upgrade-checklist/)** - Server provisioning on the blog ### External Resources - [Trellis Security Documentation](https://roots.io/trellis/docs/security/) diff --git a/trellis/updater/README.md b/trellis/updater/README.md deleted file mode 100644 index a6f42d1..0000000 --- a/trellis/updater/README.md +++ /dev/null @@ -1,256 +0,0 @@ -# Trellis Updater - -A Bash script to safely update your [Roots Trellis](https://roots.io/trellis/) installation while preserving your custom configurations. - -## Features - -- Creates a backup of your current Trellis directory -- Downloads the latest version of Trellis -- Generates a diff to see what would change -- Updates your Trellis files while preserving important configurations: - - Vault files with passwords and sensitive data - - WordPress site configurations - - User configurations - - Host configurations - - Trellis CLI configuration -- Commits changes to your Git repository - -## What This Script Preserves - -The updater script specifically preserves the following files/directories: - -### Secrets & Credentials -- `.vault_pass` - Vault password file -- `ansible.cfg` - Contains `vault_password_file` setting (CRITICAL!) -- `group_vars/all/vault.yml` -- `group_vars/development/vault.yml` -- `group_vars/production/vault.yml` -- `group_vars/staging/vault.yml` - -### Git & CI/CD -- `.git/` -- `.github/` -- `.trellis/` - -### Site-Specific Configurations -- `group_vars/development/wordpress_sites.yml` -- `group_vars/production/wordpress_sites.yml` -- `group_vars/staging/wordpress_sites.yml` -- `group_vars/all/users.yml` -- `hosts/` directory -- `trellis.cli.yml` - -### Custom PHP/Server Settings -- `group_vars/all/main.yml` - PHP memory limits, timezone, etc. -- `group_vars/production/main.yml` - PHP-FPM pool settings, MariaDB config -- `group_vars/staging/main.yml` - Environment-specific overrides -- `group_vars/development/main.yml` - Development settings - -### Custom SMTP Settings -- `group_vars/all/mail.yml` - SMTP server configuration (Brevo/Sendgrid credentials) - -### Custom Deploy Hooks -- `deploy-hooks/` - Custom deployment scripts (e.g., memory limits for wp acorn) - -### Custom Ansible Playbooks -- `database-backup.yml`, `database-pull.yml`, `database-push.yml` - Database management -- `files-backup.yml`, `files-pull.yml`, `files-push.yml` - Uploads management -- `uploads.yml` - Uploads sync playbook -- `alantin-*.yml` - alant.in (Laravel) playbooks: databases, workers, wildcard certificate - -### Custom Nginx Configurations -- `nginx-includes/` - Custom Nginx configs (SEO redirects, asset expiry, security rules) -- `roles/nginx/templates/nginx.conf.j2` - Custom Nginx main config (rate limiting, etc.) -- `roles/wordpress-setup/tasks/nginx.yml` - Patched core task file: the SSL cert/key copy tasks skip sites with `ssl.remote: true` (cert issued on the server, e.g. alant.in wildcard), plus a guard that fails early if that cert is missing. Excluded from the rsync, so **upstream changes to it are flagged in the excluded-file diff check and must be merged by hand**. Without the patch, provisioning alant.in fails trying to copy a cert from the control machine - -### Custom Documentation -- `docs/` - Project-specific documentation -- `CHANGELOG.md` - Trellis upgrade changelog -- `CHANGELOG-TRELLIS-DATABASE-UPLOADS-MIGRATION.md` - Migration notes - -## Post-Upgrade Manual Review - -After upgrading, you should manually review and potentially merge changes from the new Trellis version: - -1. **Role template changes** - Check if upstream changed any templates you've customized: - - `roles/mariadb/templates/` - If you added custom MariaDB settings - - `roles/wordpress-setup/templates/` - If you modified PHP-FPM pool templates - - `roles/nginx/templates/nginx.conf.j2` - If you customized rate limiting or other Nginx settings - - `roles/wordpress-setup/tasks/nginx.yml` - Carries the `ssl.remote` patch; re-apply it on top of any upstream change - -2. **New variables** - Check upstream `main.yml` files for new useful variables you may want to adopt - -3. **Galaxy roles** - Run `ansible-galaxy install -r galaxy.yml` to update dependencies - -## Prerequisites - -- Ansible 2.10+ (check with `ansible --version`) -- Git access to roots/trellis repository -- Backup of your current Trellis configuration (script creates this automatically) - -## Usage - -1. **Fetch latest upstream changes** (if using upstream remote): -```bash -cd ~/code/your-site-name -git fetch upstream # Assuming you have upstream remote configured -git log HEAD..upstream/master | head -20 # Review what's new -``` - -2. **Edit the script to set your project slug**: -```bash -# Open the script and update line 4 -PROJECT="your-site-name" # e.g., "example.com" -``` - -3. **Make the script executable** (first time only): -```bash -chmod +x trellis-updater.sh -``` - -4. **Run the updater script**: -```bash -./trellis-updater.sh -``` - -5. **Review the changes**: -```bash -# Check diff summary -cat ~/trellis-diff/changes.txt - -# Review detailed changes -cd ~/code/your-site-name -git status -git diff trellis/ - -# Check specific files -git diff trellis/requirements.txt -git diff trellis/CHANGELOG.md -``` - -6. **Update Ansible Galaxy roles**: -```bash -cd ~/code/your-site-name/trellis -ansible-galaxy install -r galaxy.yml --force -``` - -7. **Test in development** (if applicable): -```bash -# Quick VM test (if VM is running) -trellis vm shell --workdir /srv/www/yoursite.com/current -- wp --version --path=web/wp - -# Or full provision (takes longer) -# trellis provision development -``` - -8. **Commit the changes**: -```bash -git add trellis/ -git commit -m "Update Trellis to latest version - -- Fetch upstream changes from roots/trellis -- Preserve custom configurations (vault, wordpress_sites, PHP settings, SMTP) -- Update Galaxy roles -- Tested in development environment" - -git push origin main -``` - -## What Changed in This Version - -**Script Improvements (2026-02-09)**: -- ✅ Added timestamped backups (`~/trellis-backup-YYYYMMDD_HHMMSS`) -- ✅ Added error handling (`set -e`) -- ✅ Added project directory validation -- ✅ Added progress messages with checkmarks -- ✅ Improved diff handling (won't fail on differences) -- ✅ Added `--depth 1` to git clone (faster) -- ✅ Added comprehensive summary with next steps -- ✅ Added automatic cleanup of existing temp directories - -## Troubleshooting & Tips - -### Ansible Version Compatibility -Recent Trellis versions support Ansible 2.10+ and have removed the `ansible-core<2.19.0` constraint. If you're upgrading from an older Trellis version: - -```bash -# Check your Ansible version -ansible --version - -# Expected: ansible-core 2.10.0 or higher -# Note: Homebrew ansible 13.x includes ansible-core 2.20.x (compatible) -``` - -### Backup Directory Issues -The script now uses timestamped backups (`~/trellis-backup-YYYYMMDD_HHMMSS/`). Each run creates a new backup, so you can safely run multiple times without overwriting previous backups. - -### MariaDB Template Customizations -The rsync command will overwrite role templates. If you have customizations in: -- `roles/mariadb/templates/50-server.cnf.j2` (e.g., `max_allowed_packet`, `max_connections`) -- `roles/wordpress-setup/templates/php-fpm-pool-wordpress.conf.j2` - -You'll need to re-apply them after the upgrade. Check with: -```bash -git diff trellis/roles/mariadb/templates/50-server.cnf.j2 -``` - -### Testing Without Full Provision -Instead of running `trellis provision development` (which takes time), you can verify the upgrade works with quick VM checks: -```bash -# If VM is already running -trellis vm shell --workdir /srv/www/yoursite.com/current -- wp --version --path=web/wp -trellis vm shell --workdir /srv/www/yoursite.com/current -- wp db check --path=web/wp -``` - -### Galaxy Roles -Always use `--force` flag when updating Galaxy roles after an upgrade: -```bash -ansible-galaxy install -r galaxy.yml --force -``` - -### Diff Review Tips -The generated diff at `~/trellis-diff/changes.txt` shows file-level changes. For detailed line-by-line review: -```bash -git diff trellis/ -``` - -Look specifically for: -- New roles (e.g., `roles/redis/` in v1.26.0+) -- Changed defaults in `roles/*/defaults/main.yml` -- Template changes that might conflict with your customizations - -### Vault Password / Provision Failures -If you see "Attempting to decrypt but no vault secrets found" when running `trellis provision`: - -1. **Check `.vault_pass` exists:** - ```bash - ls -la ~/code/yoursite.com/trellis/.vault_pass - ``` - -2. **Check `ansible.cfg` has vault setting:** - ```bash - grep vault_password_file ~/code/yoursite.com/trellis/ansible.cfg - ``` - Should show: `vault_password_file = .vault_pass` - -3. **Check vault.yml files exist:** - ```bash - ls -la ~/code/yoursite.com/trellis/group_vars/*/vault.yml - ``` - -4. **Restore from backup if missing:** - ```bash - cp ~/trellis-backup/.vault_pass ~/code/yoursite.com/trellis/ - cp ~/trellis-backup/ansible.cfg ~/code/yoursite.com/trellis/ - cp ~/trellis-backup/group_vars/*/vault.yml ~/code/yoursite.com/trellis/group_vars/*/ - ``` - -## Requirements - -- Git -- Bash -- rsync - -## License - -MIT License. See [LICENSE.md](../../LICENSE.md) for details. \ No newline at end of file diff --git a/trellis/updater/manual-update.md b/trellis/updater/manual-update.md deleted file mode 100644 index af14429..0000000 --- a/trellis/updater/manual-update.md +++ /dev/null @@ -1,115 +0,0 @@ -# Step 1: Create backup directory -First, create a directory to store your backup for safety: - -```bash -mkdir -p ~/trellis-backup -``` - -# Step 2: Back up the entire current trellis directory including hidden files -Copy your entire existing Trellis setup to the backup location, preserving all permissions and hidden files: - -```bash -cp -ra ~/code/website.com/trellis/ ~/trellis-backup/ -``` - -# Step 3: Clone fresh Trellis to temporary directory -Create a temporary directory and clone the latest version of Trellis from the official repository: - -```bash -mkdir -p ~/trellis-temp -cd ~/trellis-temp -git clone git@github.com:roots/trellis.git -``` - -# Step 4: Generate diff to see what would change -Compare the fresh clone with your existing setup to understand what changes would be made: - -```bash -mkdir -p ~/trellis-diff -diff -rq ~/trellis-temp/trellis/ ~/code/website.com/trellis/ > ~/trellis-diff/changes.txt -``` - -# Step 5: Remove .git directory from the cloned Trellis to prevent conflicts -Delete the Git repository information from the fresh clone to prevent conflicts during the update: - -```bash -rm -rf ~/trellis-temp/trellis/.git -``` - -# Step 6: Update Trellis files using rsync with explicit excludes -Copy all new files to your existing Trellis setup, while carefully excluding your custom configurations and sensitive files: - -```bash -rsync -av \ - --exclude=".vault_pass" \ - --exclude="ansible.cfg" \ - --exclude=".trellis/" \ - --exclude=".git/" \ - --exclude=".github/" \ - --exclude="group_vars/all/vault.yml" \ - --exclude="group_vars/development/vault.yml" \ - --exclude="group_vars/production/vault.yml" \ - --exclude="group_vars/staging/vault.yml" \ - --exclude="group_vars/development/wordpress_sites.yml" \ - --exclude="group_vars/production/wordpress_sites.yml" \ - --exclude="group_vars/staging/wordpress_sites.yml" \ - --exclude="group_vars/all/users.yml" \ - --exclude="group_vars/all/main.yml" \ - --exclude="group_vars/all/mail.yml" \ - --exclude="group_vars/all/security.yml" \ - --exclude="group_vars/production/main.yml" \ - --exclude="group_vars/staging/main.yml" \ - --exclude="group_vars/development/main.yml" \ - --exclude="deploy-hooks/" \ - --exclude="trellis.cli.yml" \ - --exclude="hosts/" \ - ~/trellis-temp/trellis/ ~/code/website.com/trellis/ -``` - -**Note:** The excluded files contain your custom configurations: -- `main.yml` files: PHP/server settings (memory limits, PHP-FPM pool config, MariaDB settings) -- `mail.yml`: SMTP server configuration (Brevo/Sendgrid credentials) -- `security.yml`: fail2ban jails (wordpress_wp_login), bantime, maxretry, IP whitelist ⚠️ -- `deploy-hooks/`: Custom deployment scripts -These are excluded to preserve your customizations. - -# Step 7: Clean up temporary directory -Remove the temporary directory as it's no longer needed: - -```bash -rm -rf ~/trellis-temp -``` - -# Step 8: Return to project directory -Navigate back to your main project directory: - -```bash -cd ~/code/website.com -``` - -# Step 9: Check status of changes -Review what files have changed in your Git repository: - -```bash -git status -``` - -# Step 10: Review diff of changes -Examine the specific changes made to your Trellis files: - -```bash -git diff trellis/ -``` - -# Step 11: Add changes if everything looks good -Stage the updated files for committing: - -```bash -git add trellis/ -``` - -# Step 12: Commit the changes -Save the changes with a descriptive commit message: - -```bash -git commit -m "Update Trellis to latest version while preserving custom configurations" \ No newline at end of file