Deploy and Host Evolution API on Railway

Evolution API is the open-source WhatsApp REST gateway. Connect a number by scanning a QR code, then send and receive messages, media, and groups over plain HTTP — no Meta Business API approval, no per-conversation fees. This template deploys Evolution API v2.3.7 with PostgreSQL 17 and Redis 8, each on its own persistent volume, with full message history turned on.

That last part is the reason this template exists. Deploy it and it asks you for nothing.

About Hosting Evolution API

Evolution decides what to persist from seven separate DATABASE_SAVE_* environment variables, and it reads each one as a strict === "true" with no default. An unset flag is a false flag. A deployment that wires up PostgreSQL correctly but leaves those variables alone still records instances and nothing else — no messages, no contacts, no chats, no labels, no history sync. The database is attached, connected, healthy, and empty, and you find out weeks later when you go looking for a conversation.

This template sets all seven. It also mounts a volume at /evolution/instances, so the WhatsApp auth files survive a redeploy and you scan each QR code once rather than after every version bump. Redis runs with append-only persistence on its own volume instead of as a disposable cache, so live session state survives a restart. PostgreSQL mounts its volume at /var/lib/postgresql and keeps PGDATA at the default subdirectory, which is what stops the ext4 lost+found from landing inside the data directory and blocking initialization.

Everything the platform needs is baked into the image (ghcr.io/bon5co/evolution-api-railway) rather than shipped as template variables you have to fill in, so the deploy form is empty. The API key is generated for you at 48 characters, the database and cache URIs wire themselves to the private services, and telemetry is off.

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.

• Your history is actually saved — all seven DATABASE_SAVE_* flags on, so messages, contacts, chats, labels, and historic sync are written to Postgres instead of silently discarded.
• Nothing to fill in — the deploy form is empty; the API key and both connection URIs generate themselves.
• Scan each QR code once — instance auth lives on a volume, so redeploys don't disconnect your numbers.
• Durable session cache — Redis with append-only persistence on a volume, not a cache that empties on restart.
• Private by default — Postgres and Redis get no public domains; only the API is reachable, behind a 48-character key.
• Pinned, not floating — a fixed upstream version, so a redeploy gives you the build you tested.

Common Use Cases

• Customer support automation — bridge WhatsApp into your helpdesk, CRM, or n8n workflows, with the transcript retained.
• Notifications and alerts — deliver order updates, appointment reminders, or system alerts over WhatsApp at flat infrastructure cost.
• AI chat agents — put an LLM behind a real WhatsApp number and give it the conversation history to read.

Dependencies for Evolution API Hosting

• A PostgreSQL 17 service with a volume mounted at /var/lib/postgresql (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
• bon5co/evolution-api-railway — the Railway-tuned wrapper image this template deploys, and what is baked into it
• evoapicloud/evolution-api — the upstream image it is built from

Implementation Details

Three services on Railway's private network:

The wrapper image also maps Railway's injected PORT onto SERVER_PORT, which is the variable Evolution actually reads for its listen port, and clears the ext4 lost+found from the instances volume so it doesn't appear as a phantom instance in the Manager UI.

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. The Manager UI is served at /manager.