Deploy and Host Evolution API on Railway

Evolution API is an open-source REST API for WhatsApp. You link a number by scanning a QR code, then send and receive messages, media, groups and status updates over plain HTTP, with webhooks for everything that arrives. This template deploys it with PostgreSQL and Redis, fully configured.

About Hosting Evolution API

Three services, all from official upstream images:

EvolutionAPI — the REST API and the built-in web manager at /manager. Public domain, healthcheck, and a 64-character master key generated on deploy.
Postgres — instances, session credentials, contacts, chats and message history, on a volume.
Redis — cache, deliberately without a volume: a Redis container cannot write to a Railway volume, and the way it fails is to stop accepting writes altogether rather than to lose the disk quietly. Nothing here needs to survive a restart — the session credentials are in Postgres. Private network only; there is no public port pointed at it.

Every variable is filled in and described on the deploy screen. There is nothing you have to type to get a working instance.

Three things this template does that are worth knowing about:

It waits for the database before migrating. Evolution API runs Prisma migrations as the first thing it does, and exits if Postgres is not answering yet — and the script that runs them swallows the real error, so all you see is Migration failed. It is the most reported startup problem in the upstream project (issues #2529, #2605), and on a platform where services start in parallel it would hit the very first deploy. The start command here waits for the database first, and the service is allowed enough restarts to survive a database restart later on.

It pins a released version. The image is v2.3.7, the newest stable release. The latest tag is not that: it was rebuilt from an unreleased commit and matches no published version, and 2.4.0-rc1 / rc2 are release candidates. A floating tag on a service holding live WhatsApp sessions is a re-scan of every QR code waiting to happen.

It does not import your entire chat history. Upstream defaults DATABASE_SAVE_DATA_HISTORIC to on, which pulls the full prior conversation history of every number that connects. On a metered volume that is the difference between a database that grows with your traffic and one that arrives full on day one. It is off here and documented, so turning it back on is one variable.

Common Use Cases

Notifications and alerts: order confirmations, appointment reminders and delivery updates sent from your own backend over HTTP.
Chatbots and support: receive every incoming message on a webhook, answer from your own logic, and keep the conversation in your own database.
Automation platforms: it is the usual way to give n8n, Typebot or Chatwoot a WhatsApp channel — Evolution API speaks REST and webhooks, which is all any of them need.
Multiple numbers on one deployment: instances are created through the API, so one deployment can serve several numbers.

Dependencies for Evolution API Hosting

Deployment Dependencies

Evolution API — the upstream project and its official image
PostgreSQL for instances, sessions and message data
Redis for caching

Implementation Details

The master key is the whole security model. AUTHENTICATION_API_KEY creates instances and can read every message; it is generated once on deploy and sent as the apikey header. Anyone holding it holds the account.
No volume on the API service. Session credentials go to Postgres (DATABASE_SAVE_DATA_INSTANCE), so a redeploy does not disconnect linked numbers — verified by redeploying with a live instance. That same flag is why it must stay on: with it off and no other store configured, no number can connect at all.
Media is fetched from WhatsApp on demand rather than kept on disk. Set S3_ENABLED with the S3 credentials next to it if you want received media stored permanently.
Logging is turned down. Upstream enables every channel including VERBOSE and WEBSOCKET; on Railway that hits the per-deployment log rate limit and drops the lines that matter. Add them back while troubleshooting.
Timezone is UTC. The image bakes in America/Sao_Paulo.
Telemetry is off. One variable turns it back on.
One upstream quirk this template cannot fix: the JSON at / reports its own manager link as http://… because the app never trusts the proxy header. The link works — the scheme in that one hint field is wrong, and there is no setting for it.

Resource Usage and Cost

Three services use roughly 500–800 MB of RAM idle, plus 2 GB of volume on Postgres — the only service that carries one — about $10–20/month for a deployment serving a few numbers. Message volume drives it from there, mostly through Postgres.

Why Deploy Evolution API on Railway?

An API that holds long-lived WebSocket connections to WhatsApp needs to stay up, and it needs its database next to it. Railway gives it a private network to Postgres and Redis, a volume for the database that holds the sessions, a public domain with TLS for webhooks and the manager, and restarts that survive a database blip.

The alternative is a VM with a compose file, where the certificates, the private network, the restart policy and the backups are all yours — and where the first thing you meet is a migration that fails without saying why.