Deploy FalkorDB on Railway

Railway is a modern platform-as-a-service (PaaS) that makes it easy to deploy and manage applications. FalkorDB provides verified Railway templates so you can start a graph database in minutes without managing infrastructure.

Available Templates

FalkorDB offers two verified deployment templates on Railway. Choose the template that matches your workload:

Template	Best for	Notes
Single Instance	Development, testing, demos, and small production workloads	Runs one FalkorDB instance with the Browser enabled by default. Use Railway volumes and backups for persistence.
Cluster	Production workloads that need high availability or horizontal scaling across multiple graphs	Runs multiple FalkorDB nodes. Each graph is stored as a single Redis key and belongs to one hash slot, so a single large graph is not automatically split across shards.

Prerequisites

Before deploying FalkorDB on Railway, ensure you have:

• A Railway account
• Basic understanding of FalkorDB and graph databases
• A Redis-compatible client, such as redis-cli, for command-line testing

Option 1: Single Instance Deployment

The single instance template deploys a standalone FalkorDB server with the browser interface enabled by default.

Deploy the Template

1. Visit the FalkorDB Single Instance template
2. Click the Deploy button
3. Sign in to your Railway account or create one if needed
4. Railway will automatically provision and deploy your FalkorDB instance
5. Once deployment completes, open the service Variables tab to review the generated connection details

Accessing Your Instance

After deployment, you can access FalkorDB through the Browser UI, from another Railway service, or from your local machine. These paths use different endpoints:

Endpoint or variable	Use it for	Reachability
RAILWAY_PUBLIC_DOMAIN	Opening the FalkorDB Browser over HTTPS	Public internet
FALKORDB_PRIVATE_URL	Application services running in the same Railway project and environment	Railway private network only
FALKORDB_PUBLIC_URL	Local development, external clients, or redis-cli outside Railway	Public TCP proxy, if enabled
FALKORDB_PASSWORD	Browser login and client authentication	Secret value in Railway service variables

Using the Browser Interface

1. Navigate to your Railway project dashboard
2. Click on the FalkorDB service
3. Click the public domain to open the FalkorDB Browser

1. Find FALKORDB_PASSWORD in the service Variables tab
2. Use FALKORDB_PASSWORD in your browser to log in to your database

If the Browser prompts for connection fields, copy the current values from your Railway service Variables tab (FALKORDB_HOST, FALKORDB_PORT, and the username shown there) and authenticate with FALKORDB_PASSWORD.

Connecting from Another Railway Service

Use the private URL when your application runs in the same Railway project and environment as FalkorDB. Private networking keeps database traffic inside Railway and avoids exposing the FalkorDB protocol port to the public internet.

1. Open the FalkorDB service Variables tab
2. Copy FALKORDB_PRIVATE_URL
3. Add it as a variable to your application service, or reference it from the application service

Example with Python:

import os

from falkordb import FalkorDB

db = FalkorDB.from_url(os.environ["FALKORDB_PRIVATE_URL"])
graph = db.select_graph("mygraph")

result = graph.query("RETURN 'connected' AS status")
print(result.result_set)

Private URLs are not reachable from your laptop or from services in other Railway projects or environments.

Connecting from Your Local Machine

For local development or external clients, use FALKORDB_PUBLIC_URL.

Connect using redis-cli and run a test query in a single invocation:

redis-cli -u "$FALKORDB_PUBLIC_URL" GRAPH.QUERY mygraph "RETURN 'connected' AS status"

If FALKORDB_PUBLIC_URL is not available, enable a Railway TCP Proxy for the FalkorDB service and expose the internal FalkorDB protocol port.

Option 2: Cluster Deployment

The cluster template deploys a multi-node FalkorDB cluster for production workloads requiring high availability and horizontal scalability across graph keys.

Deploy the Template

1. Visit the FalkorDB Cluster template
2. Click the Deploy button
3. Sign in to your Railway account
4. Railway will provision multiple FalkorDB nodes and configure them as a cluster
5. Wait for all nodes to be deployed and the cluster to be initialized

Cluster Architecture

FalkorDB Cluster uses Redis Cluster hash slots to distribute graph keys across primary nodes:

• Primary nodes - Own hash slot ranges and serve writes for the graphs assigned to those slots
• Replica nodes - Provide redundancy and failover for primaries
• Cluster-aware clients - Follow Redis Cluster redirects and route commands to the node that owns the target graph key

Each graph lives on one shard. Clustering helps when you have many graphs or workloads that can be distributed across graph names; it does not partition a single graph across multiple shards. For more details, see Setting Up a FalkorDB Cluster.

Connecting to the Cluster

To connect to your FalkorDB cluster:

1. Apps deployed within Railway – use FALKORDB_PRIVATE_URL. Traffic stays inside Railway’s private network and never touches the public internet.
2. External clients and local development – use FALKORDB_PUBLIC_URL. This requires a Railway TCP Proxy to be enabled for the FalkorDB service.
3. Use cluster-aware clients so MOVED redirects are handled correctly.

Example with Python (internal app — swap in FALKORDB_PUBLIC_URL for external access):

import os

from falkordb import FalkorDB

# Internal: use FALKORDB_PRIVATE_URL for apps running inside the same Railway project
# External: replace with FALKORDB_PUBLIC_URL for local development or external clients
# FalkorDB.from_url() automatically detects cluster mode at connection time
# (probes INFO server) so no extra cluster flag is needed.
db = FalkorDB.from_url(os.environ["FALKORDB_PRIVATE_URL"])

graph = db.select_graph("mygraph")

graph.query("CREATE (:Person {name: 'Bob', age: 25})")
result = graph.query("MATCH (n:Person) RETURN n.name, n.age")

Using redis-cli in cluster mode:

# From inside Railway (private endpoint)
redis-cli -c -u "$FALKORDB_PRIVATE_URL"

# From your local machine or an external client (public endpoint)
redis-cli -c -u "$FALKORDB_PUBLIC_URL"

Best Practices

Security

• Use FALKORDB_PRIVATE_URL for production application traffic whenever possible
• Expose FALKORDB_PUBLIC_URL only when you need local or external access
• Treat FALKORDB_PASSWORD and connection URLs as secrets
• Rotate credentials if they are copied into logs, tickets, or shared terminals
• Disable public access paths that are not required for your workload

Data Persistence

The template provides persistent Railway volumes for FalkorDB data storage:

• Data persists across deployments and restarts
• Volumes are mounted when the service starts, not during build time
• Regular backups are recommended for production workloads
• Persistence protects against container restarts, but it is not a replacement for backups

For production deployments:

1. Confirm the FalkorDB data directory is backed by a Railway volume
2. Configure manual or automated Railway volume backups
3. Review FalkorDB durability settings for RDB snapshots and AOF logging in Data Durability

Monitoring and Logs

Railway provides built-in monitoring and logging:

1. Navigate to your FalkorDB service in the Railway dashboard
2. View real-time logs in the Logs tab
3. Monitor metrics in the Metrics tab
4. Set up alerts for service health and resource usage

Troubleshooting

Symptom	What to check
Browser login fails	Confirm the username is default, copy the latest FALKORDB_PASSWORD, and use the FALKORDB_HOST and FALKORDB_PORT values from your Railway service Variables tab.
Local redis-cli cannot connect	Use FALKORDB_PUBLIC_URL, not FALKORDB_PRIVATE_URL. Private URLs only work inside the same Railway project and environment.
FALKORDB_PUBLIC_URL is missing	Enable Railway TCP Proxy for the FalkorDB service and expose the internal FalkorDB protocol port.
Application cannot connect from Railway	Confirm both services are in the same project and environment, then use FALKORDB_PRIVATE_URL.
Cluster client receives MOVED replies	Use a cluster-aware client or redis-cli -c.
Data is missing after redeploy	Confirm the FalkorDB data directory is mounted on a Railway volume and review the service logs for startup errors.

Frequently Asked Questions 5

How long does it take to deploy FalkorDB on Railway?

Deployment typically completes in under 2 minutes. Railway provisions the service, pulls the Docker image, and starts FalkorDB automatically from the verified template.

What is the difference between FALKORDB_PRIVATE_URL and FALKORDB_PUBLIC_URL?

Private URLs only work within the same Railway project and environment (service-to-service). Public URLs use a Railway TCP Proxy and are reachable from your local machine or external clients.

Does my data persist across Railway redeployments?

Yes, if the FalkorDB data directory is mounted on a Railway volume. Volumes persist across deployments and restarts. Without a volume, data is lost on redeploy.

Can I deploy a FalkorDB cluster on Railway?

Yes. Use the FalkorDB Cluster template which provisions multiple nodes. You need a cluster-aware client to handle MOVED redirects.

How do I connect from my local machine to Railway FalkorDB?

Use FALKORDB_PUBLIC_URL with redis-cli -u. If the public URL is not available, enable Railway TCP Proxy for the FalkorDB service and expose the internal FalkorDB protocol port.