Deploy and Host FerretDB on Railway

FerretDB is an open-source MongoDB alternative — a proxy that speaks the MongoDB wire protocol while storing your data in PostgreSQL. Your existing MongoDB drivers, tools, and queries work unchanged (mongosh, Compass, any MongoDB client), but the data lives in Postgres with its ACID guarantees, mature backup ecosystem, and an Apache-2.0 license free of MongoDB's SSPL restrictions. This template deploys FerretDB 2.x correctly — with the DocumentDB-extended PostgreSQL that version 2 actually requires.

What This Template Deploys

Both services run on Railway's private network. FerretDB connects to Postgres via FERRETDB_POSTGRESQL_URL, and a persistent volume holds the database. External clients reach FerretDB through Railway's TCP proxy on the MongoDB port.

About Hosting

FerretDB 2.x has one hard requirement that trips most deployments, including older templates: it does not work with plain PostgreSQL. Version 2 stores documents using the DocumentDB extension, which builds native BSON support into Postgres for real MongoDB-compatible performance. That means the Postgres service must be the special ghcr.io/ferretdb/postgres-documentdb image, not a stock Postgres. A template pointing FerretDB 2.x at a normal Postgres simply fails.

This template uses the correct pairing: ghcr.io/ferretdb/ferretdb:2.x as the wire-protocol proxy and ghcr.io/ferretdb/postgres-documentdb as the DocumentDB-enabled backend, connected over Railway's private network. That's the difference between a working MongoDB-compatible database and a broken one — and it's where the older Railway templates, built for FerretDB 1.x against generic Postgres, fall short.

FerretDB speaks the MongoDB wire protocol, not HTTP. Clients connect on port 27017 as if to MongoDB. On Railway that means enabling the TCP proxy on the FerretDB service and using the proxy host and port as your connection string — HTTP routing won't reach it. Internal Railway services can connect over the private domain directly.

Why choose this over MongoDB: you keep MongoDB's developer experience and driver ecosystem while gaining PostgreSQL's ACID transactions, backup tooling, and an Apache-2.0 license — avoiding the SSPL terms that pushed many teams off MongoDB in the first place.

Typical cost: ~$5–10/month on Railway for FerretDB and its Postgres backend. FerretDB is free and open source; MongoDB Atlas bills per cluster-hour and storage.

How It Compares

MongoDB Atlas is the polished managed option with the fullest feature set. Self-hosted MongoDB carries the SSPL license. FerretDB's niche is MongoDB compatibility on open, ACID PostgreSQL storage — the right fit for teams that want the MongoDB API without the license or vendor lock-in.

Deploy in Under 5 Minutes

1. Click Deploy on Railway — FerretDB and the DocumentDB Postgres build automatically (~3 minutes)
2. Confirm FERRETDB_POSTGRESQL_URL points at the Postgres service and credentials are set
3. Enable Railway's TCP proxy on the FerretDB service to reach it from outside Railway
4. Connect with any MongoDB client: mongodb://user:password@:/
5. Run mongosh or point your app's MongoDB driver at it — no code changes needed

Existing MongoDB tooling — mongosh, Compass, drivers — works as-is.

Common Use Cases

• MongoDB without the SSPL license — keep the MongoDB API and drivers on Apache-2.0 storage, avoiding MongoDB's licensing terms
• Drop-in MongoDB replacement — point existing apps at FerretDB with no driver or query changes for most CRUD and aggregation workloads
• Postgres-backed document store — get MongoDB's document model with PostgreSQL's ACID transactions and backup ecosystem
• Cost control — replace per-cluster Atlas billing with flat Railway infrastructure
• Data portability — MongoDB compatibility on open SQL storage, avoiding proprietary lock-in

Configuration

> FerretDB 2.x needs the DocumentDB Postgres image, not plain Postgres. The backend must be ghcr.io/ferretdb/postgres-documentdb. Pointing FerretDB 2.x at a standard Postgres image will not work — the DocumentDB extension is what version 2 stores data with.

> Connect through Railway's TCP proxy. FerretDB speaks the MongoDB wire protocol on 27017, not HTTP. Enable the TCP proxy on the FerretDB service and use the proxy host and port in your MongoDB connection string. Internal services can use the private domain directly.

Dependencies for FerretDB Hosting

• Railway account — Hobby plan (~$5–10/month) covers both services
• Railway's TCP proxy enabled for external MongoDB client access
• A persistent volume for the PostgreSQL data (included)
• Any MongoDB driver or tool (mongosh, Compass, language drivers) to connect

Deployment Dependencies

• FerretDB GitHub Repository
• FerretDB Documentation
• DocumentDB Extension Guide
• Railway TCP Proxy Documentation

Implementation Details

The template pairs ghcr.io/ferretdb/ferretdb:2.x with ghcr.io/ferretdb/postgres-documentdb — the pre-packaged PostgreSQL that ships the DocumentDB extension FerretDB 2.x depends on. FerretDB acts purely as a translation layer: it accepts MongoDB wire-protocol connections on 27017 and converts queries into SQL executed against the DocumentDB-extended Postgres, where documents are stored with native BSON support rather than as generic JSONB.

FERRETDB_POSTGRESQL_URL carries the backend connection, assembled from Railway reference variables so the two services communicate over the private network with no exposed database port. A persistent volume backs the Postgres data directory, so your collections survive redeploys.

Because the MongoDB wire protocol is a raw TCP protocol rather than HTTP, external access goes through Railway's TCP proxy: enable it on the FerretDB service and Railway assigns a host and port for MongoDB clients. Internal Railway services can connect over the private domain without the proxy. Pin both images to matching version tags, since the DocumentDB image version corresponds to a specific FerretDB release.

Frequently Asked Questions

Why does it need a special Postgres image? FerretDB 2.x stores documents using the DocumentDB extension, which adds native BSON support to Postgres. The backend must be ghcr.io/ferretdb/postgres-documentdb — a plain Postgres image lacks the extension and won't work. Older templates built for FerretDB 1.x used generic Postgres, which no longer applies.

How do I connect from outside Railway? Enable the TCP proxy on the FerretDB service, then use the proxy host and port in a standard MongoDB connection string. FerretDB speaks the MongoDB wire protocol, so any MongoDB driver or tool connects as if to MongoDB.

Do my existing MongoDB drivers work? Yes. FerretDB implements the MongoDB wire protocol, so mongosh, Compass, and language drivers work unchanged for supported operations — the point is a drop-in replacement.

What's not supported? As of 2026, FerretDB covers most CRUD, standard indexes, and basic aggregation, but some advanced aggregation operators and Atlas-specific features aren't implemented. Test your workload before migrating.

Do my collections survive a redeploy? Yes. Data lives in the DocumentDB Postgres service, backed by a persistent volume, so collections persist across redeploys. Back it up with standard Postgres tooling.

Is it production-ready? FerretDB 2.x is stable for workloads needing MongoDB compatibility on SQL storage. As with any database, enable backups and monitoring, and validate your queries against it first.

Why Deploy FerretDB 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 FerretDB on Railway you get a MongoDB-compatible database done the 2.x way — the DocumentDB-extended PostgreSQL that version 2 requires, the two services pre-wired over a private network, TCP proxy for MongoDB clients, and a persistent volume for your data. The MongoDB API you know, on open PostgreSQL storage you own.