Deploy and Host NATS + JetStream on Railway

NATS is a lightweight, high-performance messaging system for building distributed applications and services. JetStream extends NATS with durable message storage, replay, acknowledgements, streams, and consumers, making it useful for workloads that need both fast pub/sub messaging and reliable event persistence.

About Hosting NATS + JetStream

Hosting NATS + JetStream typically requires running a NATS server with JetStream enabled, configuring client authentication, providing persistent storage for retained messages, and exposing a TCP endpoint that clients can reach.

This Railway template handles those essentials for you. It launches NATS with JetStream enabled, includes a persistent Railway volume mounted at /data for retained messages, protects client connections with an automatically generated authorization token, and automatically provisions a Railway TCP proxy for external NATS client access.

Once deployed, you can use the generated TCP proxy endpoint and authorization token to connect with the NATS CLI or any supported NATS client library, then immediately begin publishing messages, subscribing to subjects, creating streams, and configuring durable consumers.

Common Use Cases

Event-driven communication and pub/sub messaging between application services
Durable event streams, work queues, and asynchronous background processing
Reliable message delivery, replay, and consumer processing using JetStream

Dependencies for NATS + JetStream Hosting

An included persistent Railway volume mounted at /data for JetStream message storage
NATS_CONFIG and NATS_AUTHORIZATION_TOKEN environment variables for server configuration and client authentication
An automatically generated Railway TCP proxy for connecting external NATS clients to the server

Implementation Details

The template starts NATS using a configuration supplied through the NATS_CONFIG environment variable:

sh -c 'echo "$NATS_CONFIG" > /tmp/nats.conf && exec nats-server -c /tmp/nats.conf'

The default configuration enables NATS, monitoring, token-based authentication, and JetStream:

host: "::"
port: 4222
monitor_port: 8222

authorization {
  token: $NATS_AUTHORIZATION_TOKEN
}

jetstream {
  store_dir: "/data"
  max_mem_store: 32Mb
  max_file_store: 4GB
}

The attached Railway volume at /data provides persistent storage for JetStream, so retained messages and stream state can survive service restarts and redeployments.

NATS_AUTHORIZATION_TOKEN is generated automatically when the Railway template is deployed:

${{secret(32, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ")}}

The template also creates a Railway TCP proxy for the NATS client port. This gives users a public TCP host and port that can be used from the NATS CLI or other NATS clients outside the Railway private network.

Using the generated TCP proxy endpoint and authorization token, a CLI connection looks like:

nats --server nats://<tcp-proxy-host>:<tcp-proxy-port> \
  --token "$NATS_AUTHORIZATION_TOKEN" \
  server check connection

After connecting, commands such as nats stream add, nats consumer add, nats pub, and nats sub can be used to configure and interact with the server.

Applications deployed inside the same Railway project can instead use Railway's private networking where appropriate, while the TCP proxy provides a convenient path for local development, administration, and NATS CLI access from outside Railway.

Why Deploy NATS + JetStream 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 NATS + JetStream 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.