Deploy and Host Evolution API on Railway

Evolution API is the open-source WhatsApp REST gateway: connect a WhatsApp number by scanning a QR code, then send and receive messages, media, and groups over plain HTTP. This template deploys Evolution API v2.3.7 with PostgreSQL 17 for message history and Redis 8 for session cache — each on its own persistent volume.

About Hosting Evolution API

Evolution API keeps three kinds of state, and most self-hosted deployments lose at least one of them. Message, contact, and chat history goes to PostgreSQL. Connection session cache goes to Redis. Instance media and auth files are written to /evolution/instances on the container filesystem — and that last one is where typical deployments fail, because an unmounted container path is wiped on every redeploy, forcing you to re-scan the QR code for every connected number.

This template mounts a volume at /evolution/instances, so connected numbers stay connected across redeploys and version upgrades. Redis runs with append-only persistence (appendonly yes, everysec fsync) on its own volume rather than as a pure in-memory cache, so a Redis restart doesn't drop live session state. PostgreSQL uses a PGDATA subdirectory inside its mount, which avoids the initialization failure that occurs when Postgres is pointed at a volume root. Both datastores are private — neither has a public domain, and Evolution API reaches them over Railway's internal network only.

The API is protected by a 48-character AUTHENTICATION_API_KEY generated at deploy, and telemetry is disabled by default.

Why Deploy Evolution API on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Evolution API on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

• Scan the QR code once — instance auth files live on a volume, so redeploys don't disconnect your numbers.
• Durable Redis — append-only persistence on a volume, not a cache that empties on restart.
• Full history retained — messages, chats, contacts, labels, and historic sync all persisted to Postgres.
• Private by default — Postgres and Redis have no public domains; only the API is exposed.
• No per-message pricing — flat infrastructure cost instead of per-conversation WhatsApp Business API fees.

Common Use Cases

• Customer support automation — bridge WhatsApp into your helpdesk, CRM, or n8n workflows.
• Notifications and alerts — deliver order updates, appointment reminders, or system alerts over WhatsApp.
• AI chat agents — put an LLM behind a real WhatsApp number with full conversation history.

Dependencies for Evolution API Hosting

• A PostgreSQL 17 service with a volume mounted at /var/lib/postgresql/data (included in this template).
• A Redis 8 service with a volume mounted at /data (included in this template).
• A WhatsApp account to pair by QR code on first connection.

Deployment Dependencies

• Evolution API — upstream project (Apache-2.0)
• Evolution API documentation — endpoint and integration reference
• evoapicloud/evolution-api — the image this template deploys

Implementation Details

Three services on Railway's private network:

Create an instance and get a QR code to scan:

curl -X POST https:///instance/create \
  -H "apikey: $AUTHENTICATION_API_KEY" -H "Content-Type: application/json" \
  -d '{"instanceName": "main", "integration": "WHATSAPP-BAILEYS", "qrcode": true}'

Scan the returned QR code from WhatsApp on your phone, then send a message:

curl -X POST https:///message/sendText/main \
  -H "apikey: $AUTHENTICATION_API_KEY" -H "Content-Type: application/json" \
  -d '{"number": "5511999999999", "text": "Hello from Railway"}'

List connected instances with GET /instance/fetchInstances. Requests without a valid apikey header are rejected with 401.