Chapter 27: Deployment

Last Updated: 2026-03

27.2 Pre-Deployment Checklist

Run before every deployment, regardless of product type:

□ All required artifacts present and current
  (CLAUDE.md, REQUIREMENTS.md, ARCHITECTURE.md, DEPLOY.md, THIRD_PARTY.md)

□ All acceptance criteria in REQUIREMENTS.md verified as complete

□ Smoke tests pass (pytest -m smoke or equivalent)

□ Integration tests pass

□ No uncommitted changes (git status clean)

□ Vibe Coding Guardrail audit passed

□ THIRD_PARTY.md is current (all dependencies audited)

□ n8n workflows referenced by this product are active and tested

□ Rollback procedure documented and understood

---

27.3 WordPress Plugin Deployment

Build the deployment package

cd ITI/products/my-plugin/

# Remove development files from the package
rsync -av --exclude='.git' \
  --exclude='node_modules' \
  --exclude='.env' \
  --exclude='tests/' \
  --exclude='*.md' \
  . /tmp/my-plugin-build/

# Create the zip
cd /tmp
zip -r my-plugin-v1.2.3.zip my-plugin-build/

Deploy via WordPress admin

1. Log in to the target WordPress admin.
2. Navigate to Plugins > Add New > Upload Plugin.
3. Select the .zip file.
4. Click Install Now.
5. After installation, click Activate Plugin.
6. Navigate to Settings > [Plugin Name] and verify configuration.

Deploy via WP-CLI

# Install
wp plugin install /path/to/my-plugin-v1.2.3.zip --activate

# Verify
wp plugin status my-plugin

Post-deployment verification

# Verify the plugin is active
wp plugin status my-plugin

# Test the primary AJAX endpoint
curl -X POST https://yoursite.com/wp-admin/admin-ajax.php \
  -d "action=iti_my_action&nonce=TEST_NONCE&message=Hello"

# Check WordPress error log for any activation errors
tail -n 50 /path/to/wp-content/debug.log

Rollback

# Deactivate and remove the new version
wp plugin deactivate my-plugin
wp plugin delete my-plugin

# Install the previous version
wp plugin install /path/to/my-plugin-v1.2.2.zip --activate

---

27.4 Tauri Desktop App Deployment

Build the app

cd Personal/personal-assistant/  # or ITI/products/estate-manager/desktop/
npm run tauri build

Output location: src-tauri/target/release/bundle/

• macOS: *.dmg (Intel or Apple Silicon, depending on build target)

Distribute

For personal use and internal tools: distribute the .dmg file directly.

For products intended for the App Store or external distribution:

1. Code sign the app (requires Apple Developer account).
2. Notarize via xcrun altool or xcrun notarytool.
3. Distribute the notarized .dmg.

Update procedure

Tauri 2 supports auto-update via the tauri-plugin-updater. See product DEPLOY.md for the specific update server configuration.

---

27.5 Docker Service Deployment

For Python services running in Docker (when a new service is containerized):

Adding a new service to the Docker Compose stack

1. Add the service definition to docker-compose.yml.
2. Create a Dockerfile in the service’s directory.
3. Add the service to the health check procedure in ITI/infrastructure/n8n-dify/tests/test_docker_health.py.
4. Update backup.sh if the service has persistent data to back up.
5. Run the full test suite after adding the service.

Deploying a service update

cd ITI/infrastructure/n8n-dify

# Follow the pre-upgrade checklist (Chapter 5)
bash backup.sh

# Pull the new image (if using a registry)
docker compose pull my-service

# Restart the service
docker compose up -d my-service

# Verify
docker compose ps my-service
docker compose logs my-service --tail 20

---

27.6 Environment Variable Management

Every deployment requires environment variables to be configured on the target system. The required variables for each product are documented in its DEPLOY.md.

WordPress: wp_options (encrypted)

WordPress products store config in wp_options via the plugin’s settings page. API keys are encrypted at rest using ITI utilities.

Python services: .env file

# On the server, create the .env file (never committed to Git)
cp .env.example .env
vim .env  # Enter actual values

# Set permissions so only the process user can read it
chmod 600 .env

Tauri apps: OS Keychain

Desktop apps prompt the user to enter API keys on first run. Keys are stored in the macOS Keychain via KeychainService.

---

27.7 Rollback Playbook

Rollback procedures by product type:

Product Type	Rollback Procedure
WordPress plugin	Deactivate, delete, reinstall previous version
Tauri app	Run previous .dmg installer
Docker service	Pin previous image version in docker-compose.yml, docker compose up -d
Infrastructure stack	Full rollback via Chapter 5 Section 5.8

Note: For WordPress database schema changes (new tables), rollback requires also reverting the database with a backup. Document database changes in ARCHITECTURE.md and ensure backup is taken before any deployment that includes schema changes.

---

Previous: Chapter 26 — Security Standards | Next: Chapter 28 — Cursor Skills