--- title: "Deploy SurrealDB" description: "SurrealDB 4 multi-model database with auth, SurrealKV on a volume" category: "Storage" url: https://railway.com/deploy/surrealdb-3 --- # Deploy SurrealDB SurrealDB 4 multi-model database with auth, SurrealKV on a volume **[Deploy SurrealDB on Railway](https://railway.com/template/surrealdb-3)** Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/surrealdb-3/manifest.json - **Creator:** Agaz Self-Host - **Category:** Storage ## Template content ### SurrealDB https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/surrealdb.svg - **Image:** surrealdb/surrealdb:v4.0.1@sha256:408eb8e5c9436670525e2bc2634b1e50ba74ce1b447eaf0094c35f73b67f9cb6 - **Start command:** `/surreal start --log info --user root --bind [::]:8000 surrealkv:///data/surreal.db` - **Health check:** /health - **Public domain:** Yes ## Documentation # Deploy and Host SurrealDB on Railway SurrealDB is an open-source, multi-model database written in Rust. One engine stores documents, graph relations, key-value data, time series and vector embeddings, and you query all of them with SurrealQL, an SQL-like language. Clients connect over HTTP or WebSocket, with official SDKs for JavaScript, Python, Rust, Go and more. ## About Hosting SurrealDB This template runs the official `surrealdb/surrealdb` v4.0.1 image, pinned by digest, as a single service. Data is stored with SurrealKV, the on-disk engine in SurrealDB 4 (RocksDB was removed in v4), on a Railway volume mounted at `/data`, so it survives restarts and redeploys. Authentication is on from the first start: a `root` user is created with a generated 32-character password, and anonymous queries are refused. The public HTTPS domain serves the HTTP API and the WebSocket RPC endpoint that Surrealist and the SDKs use. Other Railway services can connect over the private network instead. Railway checks `/health` before routing traffic. ## Common Use Cases * Backend database for web and mobile apps that mix relational, document and graph data * Vector and full-text search store for AI agents and retrieval-augmented generation (RAG) * Real-time apps that use live queries over WebSocket, with row-level permissions defined in the database ## Dependencies for SurrealDB Hosting * The official SurrealDB container image (`surrealdb/surrealdb:v4.0.1`) * A Railway volume for the SurrealKV data files ### Deployment Dependencies * SurrealDB on GitHub: https://github.com/surrealdb/surrealdb * SurrealDB v4.0.1 release: https://github.com/surrealdb/surrealdb/releases/tag/v4.0.1 * `surreal start` options: https://surrealdb.com/docs/surrealdb/cli/start * Environment variables: https://surrealdb.com/docs/surrealdb/cli/env * Surrealist (web UI): https://app.surrealdb.com ### Implementation Details **Sign in.** The username is `root`, and the password is the `SURREAL_PASS` variable on the SurrealDB service. The default namespace and database are both `main`. The root password is set only when the datastore is first created, so changing `SURREAL_PASS` later does not change it. Use `ALTER USER` or `DEFINE USER OVERWRITE` in SurrealQL instead. **Connect with Surrealist.** Open https://app.surrealdb.com, create a connection with protocol `wss`, enter the value of `SURREALDB_WS_URL` (for example `wss://your-app.up.railway.app/rpc`), choose Root authentication, and sign in with `root` and your password. **Connect from another Railway service.** Use the reference variables `${{SurrealDB.SURREALDB_PRIVATE_URL}}` (HTTP on the private network, port 8000) and `${{SurrealDB.SURREAL_PASS}}`. The service listens on IPv4 and IPv6. **Quick test with curl:** ```bash curl -u root:YOUR_PASSWORD -H "Accept: application/json" \ -H "Surreal-NS: main" -H "Surreal-DB: main" \ --data "CREATE person SET name = 'Ada'; SELECT * FROM person;" \ https://your-app.up.railway.app/sql ``` **Notes.** - `RAILWAY_RUN_UID=0` is required. The image runs as a non-root user, and Railway volumes are owned by root, so without it the server fails with "Permission denied". - `/health`, `/version` and `/metrics` answer without login. `/metrics` reports only process statistics (CPU, memory, uptime and build version), never your data. - SurrealKV sizes its caches from the service's memory limit. To cap memory use, set `SURREAL_SURREALKV_BLOCK_CACHE_CAPACITY` and `SURREAL_SURREALKV_MAX_MEMTABLE_SIZE` (in bytes). - To remove the public endpoint, delete the Railway domain and connect only over the private network. ## Why Deploy SurrealDB 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 SurrealDB 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. ## 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. - [Neo4j 2026.10 Community](https://railway.com/deploy/neo4j-202610-community) — Neo4j graph database with APOC, Browser, Bolt TCP proxy and a volume Open this page in a browser: https://railway.com/deploy/surrealdb-3