The n8n WhatsApp AI Agent runs as a single-machine stack composed of n8n, Chatwoot, PostgreSQL, Redis, and Caddy — all orchestrated through Docker Compose on a single VPS. Caddy handles automatic HTTPS certificate issuance and renewal, so every public endpoint is served over TLS without manual certificate management. This guide covers the full release process from pre-flight validation through post-deployment verification, and explains what rollback looks like when something goes wrong.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/DevMauricio03/n8n-whatsapp-ai-agent/llms.txt
Use this file to discover all available pages before exploring further.
Infrastructure files
Before running any deployment command, make sure you understand the layout of the key files that define the stack:docker/docker-compose.yml.example— the complete stack definition; copy and adapt this for your environment.docker/Caddyfile.example— route and HTTPS configuration for all public domains.docker/initdb/— SQL scripts that create then8n,chatwoot, andagentdatabases on first boot..env.example— the canonical inventory of every environment variable the stack consumes; copy to.envand replace allCHANGE_MEvalues before deploying.- Modular Compose examples — separate Compose files provided as references for teams who prefer to manage services independently.
Release procedure
Every release — whether it is a version bump, a configuration change, or a workflow update — should follow this nine-step process to reduce risk and maintain an auditable record.Define version and scope
Agree on which image tags, workflow revisions, or configuration keys are changing in this release. Write the scope down before touching any files.
Verify no secrets or real data in the change
Review every file in the change set. Confirm that no
.env values, API tokens, customer phone numbers, or production database credentials are present in the commit or in any file being deployed.Create backups
Back up PostgreSQL, Redis, and all named volumes before touching the running stack. See Backup & Restore for the exact commands. Do not skip this step, even for small changes.
Validate the Compose configuration
Run Fix any reported errors before proceeding.
config to catch variable substitution errors and YAML mistakes before any containers are restarted:Pull updated images
Download the new image layers while the current stack is still running. This minimises downtime during the actual cutover:
Apply the deployment
Restart containers with the new configuration. The
-d flag detaches the process so the terminal is not blocking:Review health and logs
Confirm that all containers reached a running state and that no unexpected errors appear in the logs:Check the logs for each service that changed. See Day-to-Day Operations for the per-service log commands.
Run critical tests
Execute the minimum pre-release test set defined in the Testing guide: MSG-01, MSG-02, AI-03, HH-01, HH-02, TIME-01, TIME-02, DATA-01, and OPS-01. Do not consider a release complete until these pass.
Rollback procedure
If the deployment produces incorrect behaviour, crashes, or failed tests, follow this procedure to return the stack to its last known-good state.Deactivate the workflow
If the running n8n workflow is sending incorrect responses to customers, deactivate it immediately from the n8n editor before investigating the cause. Stopping incorrect output is more important than preserving uptime.
Restore previous image tags in .env
Open
.env and revert the image version variables (N8N_IMAGE, CHATWOOT_IMAGE, etc.) to the tags that were running before the release. Confirm that the previous images are still available locally or in the registry.Restore database or volume only if migration was incompatible
If the release included a database migration and the previous version cannot read the migrated schema, restore the PostgreSQL backup taken in step 3 of the release procedure. Do not restore volumes unless absolutely necessary — data written since the backup will be lost.
Re-run the critical tests
Run the full minimum pre-release test set to confirm the rollback was successful and that the previous version is operating correctly. All tests must pass before the stack is considered stable again.
Environment separation
Production and staging environments must be completely isolated. Sharing any resource between them creates risk of test data reaching real customers, or real credentials being used in experiments.| Resource | Production | Staging |
|---|---|---|
| Domain | Dedicated production domain | Separate subdomain or domain |
| WhatsApp number | Live business number | Dedicated test number |
| PostgreSQL databases | Production databases | Separate databases or server |
| Docker volumes | Production volumes | Separate named volumes |
| Credentials (n8n, API keys) | Production secrets | Separate test secrets |
| Data files (XLSX, price images) | Live data files | Test or fictitious data files |
Do not use experimental workflow changes or AI prompt variations against the production WhatsApp number. Real customers will receive those responses. Always validate changes on the staging environment with a test number first.
Scaling guidance
This stack is designed to run efficiently on a single VPS for small to medium conversation volumes. If you reach the limits of a single machine, several architectural decisions must be made before horizontal scaling is safe:- Measure first — profile CPU, RAM, disk I/O, and n8n execution duration under real load before concluding that scaling is necessary.
- Enable n8n queue mode — the default n8n configuration runs all executions in a single process. Queue mode distributes work across worker containers and is required before running more than one n8n instance.
- Separate PostgreSQL and Redis — move both to dedicated servers or managed services before adding application replicas, so that state is not split across hosts.
- Add compatible file storage — n8n binary data and Chatwoot attachments must be stored in a shared, network-accessible location (for example, S3-compatible object storage) before multiple app containers can serve the same files.
- Design for high availability — single-machine Docker Compose does not provide automatic failover. HA requires a load balancer, health checks, and a plan for stateful service restarts.
- Incorporate monitoring and alerting — add metrics collection and alerting before scaling so that problems in individual instances are visible.