--- title: "Deploy Velix API | (Just Updated) Self-Hosted WhatsApp REST API, Numbers Actually Connect" category: "Automation" url: https://railway.com/deploy/velix-api-v100-or-self-hosted-whatsapp-r --- # Deploy Velix API | (Just Updated) Self-Hosted WhatsApp REST API, Numbers Actually Connect **[Deploy Velix API | (Just Updated) Self-Hosted WhatsApp REST API, Numbers Actually Connect on Railway](https://railway.com/template/velix-api-v100-or-self-hosted-whatsapp-r)** - **Creator:** SuperSlowSloth - **Category:** Automation - **Total deploys:** 1 ## Template content ### postgres - **Image:** postgres:17.10-trixie ### velix - **Image:** ghcr.io/bon5co/velix-railway:latest - **Health check:** /health - **Public domain:** Yes ### redis - **Image:** redis:8.2.1 - **Start command:** `/bin/sh -c 'rm -rf /data/lost+found && chown -R redis:redis /data && exec docker-entrypoint.sh redis-server --requirepass "$REDIS_PASSWORD" --appendonly yes --dir /data'` ## Documentation # Deploy and Host Velix API on Railway Velix API is a self-hosted WhatsApp REST API written in Go: connect several WhatsApp numbers to one deployment, send and receive messages over a plain REST interface, get webhooks for everything that happens, and drive it from n8n, a chatbot, or your own backend — without Meta's Cloud API per-message pricing. This template deploys it with Postgres, Redis and a volume already wired, **and with the three Railway-specific defects that make the other listings in this category unusable already fixed**. Every claim below was reproduced against the upstream image before this template was published. ## About Hosting **The volume has to be repaired or you can never connect a number.** Railway mounts volumes owned by uid 0; the Velix image runs as uid 65532 and ships distroless, so it has no shell and no start command can fix it from the outside. Deployed that way the service looks perfect — it logs `WhatsApp engine started`, it answers the healthcheck, the dashboard is green — and then the first real call fails: ``` POST /v1/instances -> 500 INTERNAL_ERROR error: "register in engine: create store dir: mkdir /data/instances: permission denied" ``` Not one WhatsApp number can be paired, and the volume stays empty. This template's image repairs the mount's ownership before the app starts and drops back to uid 65532 immediately after, which it prints to the deploy log so you can read it back: ``` [railway-entrypoint] volume /data owned by uid 0, repairing to 65532 [railway-entrypoint] volume ready owner=65532:65532 store=/data/instances POST /v1/instances -> 201 {"status":"disconnected"} ``` Verified on this exact template: instances created, sessions written under `/data/instances`, and both still there after a redeploy. **Signup is closed, and your admin account already exists.** `POST /v1/auth/register` is open to the entire internet in Velix 1.0.0 — it creates a workspace and hands the caller `role: admin`. There is no environment variable that turns it off; the `REGISTRATION_ENABLED` setting you may see on other deploy forms appears nowhere in the binary. Anyone who finds your URL can run their own WhatsApp instances on your container, on your volume, on your bill. Here the gateway in front of the app answers `/v1/auth/register` with 403, and your own workspace is created on first boot from `VELIX_ADMIN_PASSWORD` — a Railway `secret`, visible in the variables panel, applied at creation and never regenerated afterwards. Log in with `admin@velix.local` and that password. If you want public signup back, set `VELIX_PUBLIC_REGISTRATION=true` on the service. **Brute force on the login endpoint is throttled.** Upstream applies no rate limit at all — 80 consecutive wrong-password requests to `/v1/auth/login` return 80 × 401 with no backoff. The gateway limits login and register to 10 requests/minute per client, keyed on the real client address from `X-Forwarded-For`, because on Railway every request arrives from the edge network and a limiter keyed on the socket peer would put the whole internet in one bucket. Railway replaces any inbound `X-Forwarded-For`, so the key cannot be forged. **What runs.** Three services: the Velix app (public, with a volume for session stores and media), Postgres (instances, messages, workspaces, API keys), and Redis — required, not optional; the app exits with `REDIS_URL is required` without it. The app waits for both to accept connections before starting, so the first deploy does not lose a restart cycle racing its own database. **Cost.** A single compiled Go binary plus a small gateway, so the app service is light next to browser-based WhatsApp gateways that drive a headless Chromium per number. Railway bills by usage; Velix, Postgres and Redis are all free and open source. ## Why Deploy Velix API on Railway? Railway gives you the HTTPS domain WhatsApp webhooks and the QR pairing flow need, a private network for Postgres and Redis, and persistent volumes — with no reverse proxy, no certificate renewal and no VPS to patch. This template makes that a one-click deploy that is actually usable the moment it turns green. ## Common Use Cases - **WhatsApp automation from n8n** — Velix ships a native n8n community node, so flows call it directly instead of hand-built HTTP requests. - **Customer support on several numbers** — one deployment manages multiple WhatsApp accounts, each addressed independently through the REST API, with a Chatwoot integration built in. - **Transactional and alert messaging** — order updates, OTPs, and reminders sent from your own backend over a REST call, with delivery status pushed back through webhooks. - **AI agents that answer on WhatsApp** — point the webhook at your agent and reply through the same API. ## Dependencies for Velix API Hosting - **PostgreSQL** — workspaces, users, API keys, instance metadata, messages. - **Redis** — required by the app for caching and queues; it refuses to start without it. - **Persistent volume** — WhatsApp session stores (`/data/instances`) and media (`/data/media`). Losing it means re-pairing every number. ### Deployment Dependencies - Upstream project: [Velix API](https://docs.dokploy.com/docs/templates/velix-api) (`ghcr.io/paulolinder/velix-api`), pinned to `1.0.0`. - Railway-tuned image: [`bon5co/velix-railway`](https://github.com/bon5co/velix-railway) (`ghcr.io/bon5co/velix-railway`), which adds only the volume repair, the first-boot workspace and the gateway described above. - A WhatsApp account per instance you connect (pairing is by QR code from the app). ### Implementation Details Variables you set: none are required. `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET` and `VELIX_ADMIN_PASSWORD` are all filled in for you by the template, and the last two are generated secrets unique to your deployment. Baked into the image so the deploy form stays empty: `HTTP_HOST=127.0.0.1`, `HTTP_PORT=8090` (the app listens privately behind the gateway, which honours Railway's injected `PORT`), `ENGINE_STORE_PATH=/data/instances`, `MEDIA_STORAGE_PATH=/data/media`, `ENGINE_AUTO_RECONNECT=true`, `VELIX_ADMIN_EMAIL=admin@velix.local`, `VELIX_PUBLIC_REGISTRATION=false`, `VELIX_AUTH_RATE=10r/m`, `VELIX_MAX_BODY_SIZE=100m`. After deploying: open `https:///admin/`, log in as `admin@velix.local` with `VELIX_ADMIN_PASSWORD` from the variables panel, create an instance, and scan the QR code with the phone you want to connect. ## Similar templates - [N8N Main + Worker](https://railway.com/deploy/n8n-main-worker) — Deploy and Host N8N with Inactive worker. - [Evolution API with n8n](https://railway.com/deploy/evolution-api-with-n8n) — [Jul'26] WhatsApp automation platform using Evolution API, n8n & PostgreSQL - [Postgres Backup](https://railway.com/deploy/postgres-s3-backups) — Cron-based PostgreSQL backup to bucket storage Open this page in a browser: https://railway.com/deploy/velix-api-v100-or-self-hosted-whatsapp-r