Deploy Novu

Deploy and Host Novu on Railway

Novu is open-source notification infrastructure. Instead of scattering SendGrid calls, Firebase pushes and Twilio SMS through your codebase, you define a workflow once — in-app inbox, email, SMS, push and chat, with delays, digests and preferences — and fire it from your backend with one API call. Product teams use it to stop rebuilding fan-out and retry logic for every new notification, and to get a real in-app notification bell without writing a websocket tier.

Self-host Novu on Railway and you get the whole production topology, not a single container. This template runs the four Novu services separately: the API that receives triggers, a worker that drains the BullMQ queues and delivers messages, a websocket service that pushes notifications into the browser, and the dashboard. Behind them sit MongoDB, Redis for queues and caching, and an object storage bucket for attachments. Deploy Novu once and every piece is wired over private networking before you open the URL.

Getting Started with Novu on Railway

Open the dashboard service's public URL. There are no default credentials — the first visitor creates the owner account, so sign up with your email and password and name your organization. That account becomes the administrator, and Novu creates Development and Production environments automatically. Then set DISABLE_USER_REGISTRATION to true on the API service and redeploy, or anyone who finds the URL can register.

Click Create workflow, name it, and add an In-App step. Fill in a subject and body — the right-hand panel previews the inbox card as you type. Open API Keys, copy the Development key and trigger the workflow from your backend. Each trigger appears under Activity within seconds, and a run reaching COMPLETED with Message sent successfully proves the API, queue and worker are healthy. Subscribers then shows the recipient Novu created. Add Email or SMS steps and connect your provider in the Integration Store.

About Hosting Novu

Novu sits between your application and the delivery providers you already pay for. Your code sends one event; Novu decides which channels to use, in what order and with what content, honouring each subscriber's preferences. Self-hosting matters because notification payloads carry real user data — orders, security alerts, invoices — and provider credentials stay on infrastructure you control.

Key capabilities:

• Multi-channel workflows — in-app, email, SMS, push and chat steps in one visual editor
• Digest and delay steps — batch a burst of events into one message
• Embeddable Inbox — React, Next.js, Vue and JS components for the notification bell
• Activity feed — per-run logs showing which step delivered or failed

The architecture is deliberately split. The API handles triggers, dashboard traffic and Inbox endpoints, then hands work to Redis. The worker runs four BullMQ consumers and does the real delivery, so a burst of triggers never blocks an HTTP request. The websocket service reads a queue and pushes unread counts into open tabs. The dashboard is a static SPA; the bucket holds attachments in flight.

Why Deploy Novu on Railway

Novu's four services plus two datastores are tedious to wire up by hand.

• Every service deploys pre-configured and connected over private networking
• MongoDB and Redis are managed, with volumes attached
• Object storage is a Railway bucket instead of a MinIO sidecar
• Public HTTPS domains generated for the API, dashboard and websocket tier
• Scale the worker independently as delivery volume grows

Common Use Cases

• Transactional product notifications — order status, invoice ready or deployment finished, sent to an in-app inbox and email from one trigger
• Security and account alerts — sign-in, password change and 2FA notices routed to the channel each user enabled
• Digested activity summaries — collapse a noisy comment stream into one daily digest

Dependencies for Novu

• ghcr.io/novuhq/novu/api:3.19.0 — REST API, dashboard backend, Inbox endpoints
• ghcr.io/novuhq/novu/worker:3.19.0 — BullMQ consumers that execute workflow steps
• ghcr.io/novuhq/novu/ws:3.19.0 — socket.io service for real-time inbox updates
• ghcr.io/novuhq/novu/dashboard:3.19.0 — the workflow editor app
• MongoDB 8 — workflows, subscribers, messages, logs
• Redis 8.2 — BullMQ queues and cache
• Railway object storage bucket — trigger attachments

All four images come from one release and share a schema and job format, so keep them on the same tag when upgrading.

Environment Variables Reference

Deployment Dependencies

• Source repository: github.com/novuhq/novu
• Container images: ghcr.io/novuhq
• Docs: docs.novu.co
• Runtime: Node.js 22, MongoDB 8, Redis 8

Hardware Requirements for Self-Hosting Novu

Message and log volume drives MongoDB growth. Tune NOTIFICATION_RETENTION_DAYS at high trigger rates.

Self-Hosting Novu with Docker

Novu publishes a community Docker Compose stack. These shell commands clone it and start every service locally:

git clone https://github.com/novuhq/novu.git
cd novu/docker/community
cp .env.example .env
docker compose up -d

The setup script fills JWT_SECRET, STORE_ENCRYPTION_KEY and NOVU_SECRET_KEY. Writing the .env by hand, generate them yourself — the encryption key must be exactly 32 characters, which -hex 16 produces:

openssl rand -hex 32   # JWT_SECRET
openssl rand -hex 16   # STORE_ENCRYPTION_KEY (32 characters)
openssl rand -hex 32   # NOVU_SECRET_KEY

That Compose stack uses LocalStack for storage and puts MongoDB on the application host. This template replaces both with managed services, as Novu's own docs recommend before production.

How Much Does Novu Cost to Self-Host?

The community edition is open source under the MIT licence, so the software is free with no seat limits and no message caps. Novu Cloud is the hosted commercial offering, priced per monthly event. Self-hosting on Railway costs only infrastructure: four small containers, managed MongoDB and Redis, and object storage. You still pay your own delivery providers — Novu orchestrates them, it does not resell them.

FAQ

What is Novu? Novu is open-source notification infrastructure: one API and one visual workflow editor for in-app, email, SMS, push and chat notifications, instead of integrating each provider separately in your code.

What does this Railway template deploy? The Novu API, worker, websocket and dashboard containers, plus managed MongoDB, Redis and an object storage bucket. The API, dashboard and websocket services get public HTTPS domains; the worker stays private.

Why does Novu need both MongoDB and Redis? MongoDB is the system of record for workflows, subscribers, messages and logs. Redis backs the BullMQ queues carrying work from the API to the worker, and doubles as the cache and socket.io adapter — which is why the websocket service needs it too.

Do I need an email or SMS provider to try self-hosted Novu? No. The In-App channel works with zero configuration and is the fastest way to confirm the deployment is healthy. Other channels need your own provider credentials, added in the Integration Store.

How do I add the notification inbox to my app with self-hosted Novu? Install @novu/react (or the Next.js, Vue or JS package) and render `` with your application identifier, the subscriber ID, and backendUrl and socketUrl pointing at this template's API and websocket domains instead of Novu Cloud.

How do I disable public signup on self-hosted Novu? Set DISABLE_USER_REGISTRATION=true on the API service and redeploy. The check runs inside the registration handler, so POST /v1/auth/register is rejected outright — not merely hidden in the interface.

How do I upgrade Novu on Railway? Move all four Novu services to the same new image tag and redeploy. They share a schema and job format, so leaving one behind can leave workflows connected but idle.