---
title: "Deploy YugabyteDB"
description: "PostgreSQL-compatible distributed SQL, secure from boot, persistent."
category: "Storage"
url: https://railway.com/deploy/yugabytedb
---

# Deploy YugabyteDB

PostgreSQL-compatible distributed SQL, secure from boot, persistent.

**[Deploy YugabyteDB on Railway](https://railway.com/template/yugabytedb)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/yugabytedb/manifest.json

- **Creator:** wotonews
- **Category:** Storage

## Template content

### yugabytedb

- **Image:** wotonews/yugabytedb:v2026.1.2.0-1

## Documentation

# 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](https://github.com/contourkde/postgres) 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:

| | |
| :--- | :--- |
| **YSQL user / password** | `yugabyte` + the generated `YSQL_PASSWORD` variable — **yugabytedb service → Variables tab** |
| **YCQL user / password** | `cassandra` + the same generated password (set `YCQL_PASSWORD` before first boot to differ) |
| **Connection (private network)** | `postgres://yugabyte:${{yugabytedb.YSQL_PASSWORD}}@${{yugabytedb.RAILWAY_PRIVATE_DOMAIN}}:5433/yugabyte` |

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`](https://hub.docker.com/r/yugabytedb/yugabyte) (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

| Name | Required | Default | Description |
| :--- | :---: | :--- | :--- |
| `YSQL_PASSWORD` | **yes** | *generated* | Password for YSQL user `yugabyte` (and YCQL user `cassandra`). Applied on first boot via `ALTER ROLE`. |
| `YCQL_PASSWORD` | no | = `YSQL_PASSWORD` | Separate password for the YCQL user — set before first boot if you want it to differ. |
| `YSQL_URL` | no | *auto-composed* | Private-network PostgreSQL connection string — do not edit. |
| `YB_BASE_DIR` | no | `/home/yugabyte/yb_data` | Data/certificate root (the volume mount). |

## 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

```bash
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:

```bash
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:

```bash
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.


## Similar templates

- [RustFS | (Just Updated) S3 Object Store, Public URL and Keys Set](https://railway.com/deploy/rustfs-or-just-updated-s3-object-store-p) — S3-compatible object store, keys and public URL preset, volume kept
- [TimescaleDB](https://railway.com/deploy/timescaledb-railway-template) — A PostgreSQL-based time-series database for analytics on Railway.
- [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play.

Open this page in a browser: https://railway.com/deploy/yugabytedb