Deploy YugabyteDB

Deploy and Host YugabyteDB with Railway

YugabyteDB is an open-source, PostgreSQL-compatible distributed SQL database: it speaks the PostgreSQL wire protocol, so your existing Postgres drivers and SQL keep working, while adding horizontal scale, Raft-based replication, and a Cassandra-compatible API (YCQL). This template deploys a single-node universe, secure from first boot: TLS certificates are generated automatically, authentication is enforced, the default credentials are rotated to a generated password, and everything lives on a persistent volume so redeploys never lose data.

About Hosting YugabyteDB

Hosting YugabyteDB on Railway runs the official yugabytedb/yugabyte:2026.1.2.0-b137 image (plus a thin boot wrapper) as a private-network service with a persistent volume at /home/yugabyte/yb_data. That directory holds the database, the auto-generated TLS certificates, and the yugabyted state — so the universe survives redeploys and restarts with the same identity and encryption keys.

yugabyted start --secure gives you:

• YSQL — the PostgreSQL-compatible API on port 5433 (inside the private network).
• YCQL — the Cassandra-compatible API on port 9042.
• yugabyted web UI on port 15433 (private by default).
• TLS everywhere and password authentication — no insecure mode, ever.

On first boot, upstream writes random passwords for the default users (yugabyte for YSQL, cassandra for YCQL) to a file inside the data directory. The wrapper immediately rotates both to the generated YSQL_PASSWORD and deletes that file — your credentials exist only in the database and your service variables.

Is this PostgreSQL?

YSQL is the PostgreSQL query layer (a fork of it): psql connects, PG drivers work, most Postgres SQL and many extensions (pgcrypto, pg_stat_statements, pgvector, …) are available. Underneath, storage, replication, sharding, and backups are YugabyteDB's own — it is not a Postgres server with plugins, it is a distributed database with a Postgres-compatible face. Use it when you outgrow a single Postgres node and want a scale-out path later; use our plain PostgreSQL template when one node is all you need.

Login credentials

YugabyteDB has no web login screen exposed by default (the UI port stays private; see below). Connect with:

The template pre-composes that string as YSQL_URL on the service. The password applies on first boot only — afterwards rotate it with ALTER ROLE yugabyte PASSWORD '...' (YSQL) or ALTER ROLE cassandra WITH PASSWORD = '...' (YCQL).

Why Deploy YugabyteDB on Railway?

• Secure from first boot: TLS + authentication on by default; the insecure mode upstream offers is deliberately not used.
• Zero-config secrets: the database password is generated at deploy time; nothing is hardcoded.
• Persistent by default: data and certificates live on the volume, so redeploys keep the same universe.
• One platform: host it next to your apps with private networking — no public exposure needed.
• Postgres compatibility: point any PG driver at port 5433 and go.

Common Use Cases

• PostgreSQL-flavored backend for self-hosted apps that want a scale-out path without changing drivers.
• Multi-model workloads: relational (YSQL) today, Cassandra-style (YCQL) queries tomorrow.
• Learning distributed SQL on a real deployment with zero setup friction.
• Staging replica of a larger YugabyteDB universe.

Dependencies for YugabyteDB Hosting

• Docker image: yugabytedb/yugabyte:2026.1.2.0-b137 (official, pinned)
• Ports: YSQL 5433, YCQL 9042, web UI 15433 (all private-network by default)

Deployment Dependencies

• Source: https://github.com/yugabyte/yugabyte-db (upstream, Apache-2.0)
• Image source of truth: this repository's Dockerfile
• Docs: https://docs.yugabyte.com/stable/

Environment Variables

Connect From Another Service

In the same Railway project, reference the composed string directly:

DATABASE_URL = ${{yugabytedb.YSQL_URL}}

Traffic stays on Railway's private network (yugabytedb.railway.internal). No public domain is generated for the database by default.

Need external access? Create a TCP proxy on the yugabytedb service for port 5433 (Settings → Networking, or railway tcp-proxy create --port 5433 --service yugabytedb). Clients then connect with sslmode=require — the server certificate is auto-generated, so use require, not verify-full, unless you fetch the CA from the volume first. YCQL (9042) needs TLS likewise; the yugabyted UI (15433) has no authentication of its own — keep it private and inspect it via railway ssh -c 'curl -s localhost:15433' or a temporary port-forward instead of exposing it.

Local Setup

cp .env.example .env   # edit YSQL_PASSWORD
docker build -t wotonews/yugabytedb:v2026.1.2.0-1 .
docker run -d --name yugabytedb -p 5433:5433 --env-file .env \
  -v ybdata:/home/yugabyte/yb_data wotonews/yugabytedb:v2026.1.2.0-1
# first boot takes a few minutes (cert generation + universe init)
psql "postgres://yugabyte:change-me@localhost:5433/yugabyte?sslmode=require"

Deploy to Railway

Deploy this template from the Railway marketplace, or from the repository root:

railway init --name my-yugabytedb
railway add --service yugabytedb
railway variables set YSQL_PASSWORD=$(openssl rand -hex 12)
railway deploy --image wotonews/yugabytedb:v2026.1.2.0-1
railway volume add --mount-path /home/yugabyte/yb_data --service yugabytedb

Sizing

First boot needs a few minutes for certificate generation and universe initialization. Single-node YugabyteDB runs comfortably at 2 vCPU / 4 GB RAM (Railway's default-adjacent sizing); lower tiers work for evaluation but the YSQL layer is memory-hungry — expect slow first queries below ~2 GB.

Backups

This template does not include managed backups. Use ysql_dump (a pg_dump fork) over railway ssh on a schedule, or enable Railway's volume backup features available on plans that include them:

railway ssh --service yugabytedb -c \
  './bin/ysql_dump "sslmode=require" -U yugabyte -d yugabyte -f /home/yugabyte/yb_data/backup.sql'

Scaling out

This is a single-node universe (replication factor 1) — the building block for apps that want distributed SQL without cluster overhead. YugabyteDB scales horizontally by adding nodes with yugabyted start --join; on Railway that means additional services with their own volumes joining this one over the private network. Treat that as an advanced follow-up, not a template toggle.