# openrail

> Railway's workflow on your own servers. Open source and self-hosted: one command turns any Linux VM into a canvas of services with git deploys, databases, logs and rollbacks. You pay only for the VM.

## Get started

- [Quick start](https://openrail.app/docs/quick-start.md): Install openrail on a Linux VM, open the console, deploy a GitHub repo and add Postgres.
- [The basics](https://openrail.app/docs/basics.md): openrail organises your apps into projects, environments, services and deployments, the same way Railway does, and runs them on hosts you own.
- [Coming from Railway](https://openrail.app/docs/coming-from-railway.md): openrail follows Railway names, variables and config files, so most projects move over unchanged; this page lists every difference in v0.1.
- [Production checklist](https://openrail.app/docs/production-checklist.md): Work through this list before you put real traffic on an openrail install.

## Set up

- [Install](https://openrail.app/docs/guides/install.md): Install openrail on a fresh Linux VM with one command, or walk through a guided setup that asks for your domain and email.
- [Your domains](https://openrail.app/docs/guides/console-domain.md): Serve the console and your services' generated names from your own domain instead of sslip.io, at install time or later.
- [Firewall](https://openrail.app/docs/guides/firewall.md): Open only the ports openrail needs, with your cloud provider's firewall, the installer's --firewall rules, or ufw.
- [Email (SMTP)](https://openrail.app/docs/guides/smtp.md): Connect an SMTP server so invites, password resets, email verification and alerts go out by email.
- [GitHub App](https://openrail.app/docs/guides/github-app.md): Create a GitHub App for your install so openrail can read private repos and deploy on every push, without copying keys by hand.
- [Backups bucket](https://openrail.app/docs/guides/backups-bucket.md): Point openrail at any S3-compatible bucket so every database and volume is backed up off the host and can be restored to a copy.
- [Add a host](https://openrail.app/docs/guides/add-a-host.md): Join another Linux VM with one command to run more replicas, databases or builds, or to add a second public entry point.
- [Cloudflare in front](https://openrail.app/docs/guides/behind-cloudflare.md): Proxy your domains through Cloudflare while openrail keeps issuing certificates and logs your visitors' real IP addresses.
- [Set up the CLI](https://openrail.app/docs/guides/cli-setup.md): Install the openrail CLI on your laptop or in CI, log in to your console, and optionally make it answer to railway.
- [Members, roles and 2FA](https://openrail.app/docs/guides/members-roles-2fa.md): Invite people with a role, limit them per project, turn on two-factor authentication, and read the audit log.
- [Upgrading and host maintenance](https://openrail.app/docs/guides/upgrading.md): Upgrade openrail with one command that reverts itself if the new version is unhealthy, and take hosts out for OS work without downtime.
- [Restore](https://openrail.app/docs/guides/restore.md): Pick the restore that matches what you lost, a database, a volume, the control plane's state or the whole control host, and follow its steps.

## Guides

- [Deploy from GitHub](https://openrail.app/docs/guides/deploy-from-github.md): Connect a GitHub repo to a service and openrail builds and deploys every push to its branch.
- [Deploy a Docker image](https://openrail.app/docs/guides/deploy-docker-image.md): Run any public or private Docker image as a service, with the same variables, domains and scaling as a built service.
- [Deploy with the CLI](https://openrail.app/docs/guides/deploy-with-cli.md): `openrail up` uploads the current directory, builds it on your hosts and streams the logs until the deploy is live.
- [Config as code](https://openrail.app/docs/guides/config-as-code.md): Keep a service's build and deploy settings in your repo with `railway.json`, `railway.toml`, `openrail.yaml` or `openrail.json`.
- [Move a project from Railway](https://openrail.app/docs/guides/import-from-railway.md): Move a Railway project to openrail by recreating its services, copying its variables and moving its database data; the one-step importer comes in a later release.
- [Move a database from Railway](https://openrail.app/docs/guides/move-database-from-railway.md): Copy a database from Railway into an openrail database service with one pipe through `openrail connect`.
- [Import Docker Compose](https://openrail.app/docs/guides/import-docker-compose.md): Turn a `docker-compose.yml` into services on the canvas, staged for you to review before anything deploys.
- [Templates and the Deploy on openrail button](https://openrail.app/docs/guides/templates.md): Deploy ready-made apps such as n8n, Umami or Uptime Kuma in one click, and add a Deploy on openrail button to your own README.
- [Add Postgres, MySQL, Redis or MongoDB](https://openrail.app/docs/guides/databases.md): Add a database in one click; it gets a volume, generated credentials and the same variable names Railway uses.
- [Variables and references](https://openrail.app/docs/guides/variables.md): Set environment variables per service, share them across an environment, and reference other services with `${{Service.VAR}}`.
- [Staged changes and environment sync](https://openrail.app/docs/guides/staged-changes.md): Edits collect as staged changes that you review as a diff and apply together with one Deploy, and Sync copies changes between environments.
- [Custom domains and HTTPS](https://openrail.app/docs/guides/custom-domains.md): Give a service a generated HTTPS name with no DNS setup, or put it on your own domain with a Let's Encrypt certificate issued and renewed for you.
- [Use all cores](https://openrail.app/docs/guides/use-all-cores.md): Run one process per vCPU in each replica so single-threaded runtimes like Node use every core of the host.
- [Replicas and zero-downtime deploys](https://openrail.app/docs/guides/replicas-zero-downtime.md): Run several replicas of a service across your hosts and deploy new versions without dropping requests.
- [Health checks](https://openrail.app/docs/guides/health-checks.md): A health check tells openrail when a new deployment is ready for traffic and when a running replica should be taken out of routes.
- [Rollbacks](https://openrail.app/docs/guides/rollbacks.md): Roll back to an earlier deployment and get its exact image and the variables it ran with.
- [Cron jobs](https://openrail.app/docs/guides/cron-jobs.md): Run a service on a schedule instead of keeping it running.
- [Volumes](https://openrail.app/docs/guides/volumes.md): Give a service persistent storage that survives deploys and restarts.
- [Backups and restore to a copy](https://openrail.app/docs/guides/backups.md): Back up databases and volumes to any S3-compatible bucket, and restore to a new copy at a point in time without touching the original.
- [Database major upgrades](https://openrail.app/docs/guides/database-major-upgrades.md): Move a database to a new major version by restoring a dump into a copy, then promoting it.
- [Monorepos and watch paths](https://openrail.app/docs/guides/monorepos.md): Deploy several services from one repo, each from its own directory, and build only the ones whose files changed.
- [Pre-deploy migrations](https://openrail.app/docs/guides/pre-deploy.md): Run a command such as a database migration before each new version starts serving.
- [Private networking](https://openrail.app/docs/guides/private-networking.md): Services in one environment reach each other by name over a private network that spans every host.
- [Quarantined environments](https://openrail.app/docs/guides/quarantined-environments.md): Block outbound internet traffic from an environment, with an allowlist, while its private network keeps working.
- [Monitors and alerts](https://openrail.app/docs/guides/monitors.md): Get an email or webhook when a service's CPU, memory, disk or error rate stays above a threshold.
- [Email and notifications](https://openrail.app/docs/guides/email-notifications.md): Send password resets, invites and alerts by email, choose which events reach you, and receive signed webhooks.
- [Control plane backup](https://openrail.app/docs/guides/control-plane-backup.md): The control plane snapshots its database every hour to the host's disk; copy those snapshots off the host so you can restore after a disk loss.
- [Rebuild the control host](https://openrail.app/docs/guides/rebuild-control-host.md): What to do when the control host is lost in 0.1.0, what is kept safe, and what the planned one-command rebuild will do.
- [Rotate the master key](https://openrail.app/docs/guides/rotate-master-key.md): Rotating the key that encrypts every secret in the control plane is not available in 0.1.0; this page says how to protect the key until it is.
- [Troubleshooting failed deploys](https://openrail.app/docs/guides/troubleshooting.md): Every failed or crashed deployment shows one sentence that names the cause; this page explains each one and what to do.

## Reference

- [Install options](https://openrail.app/docs/reference/install-options.md): Every flag of the installer, each also readable from a `FIFTY_<FLAG>` environment variable.
- [Service settings](https://openrail.app/docs/reference/service-settings.md): Every setting a service has, with its default and the Railway setting it matches.
- [Config file schema](https://openrail.app/docs/reference/config-file.md): The fields `railway.json`, `railway.toml`, `openrail.yaml` and `openrail.json` accept, with what each one sets.
- [Variables reference](https://openrail.app/docs/reference/variables.md): The variables openrail provides to every replica, their Railway aliases, the reference syntax and the variables that change settings.
- [Deployment statuses](https://openrail.app/docs/reference/deployment-statuses.md): The labels a deployment shows on the card, in the panel, in the CLI and in webhooks, and what each one means.
- [Log filter syntax](https://openrail.app/docs/reference/log-filters.md): Filter deploy, build and HTTP logs in the console and with `openrail logs -f` using Railway's filter syntax.
- [Templates](https://openrail.app/docs/reference/templates.md): The database and app templates that ship with openrail v0.1.
- [API](https://openrail.app/docs/reference/api.md): The openrail REST API serves everything the console and the CLI do, with the same roles and audit log.
- [Agent protocol](https://openrail.app/docs/reference/agent-protocol.md): Agents connect out to the control plane over one WebSocket and reconcile their host to the desired state they receive.
- [Architecture](https://openrail.app/docs/reference/architecture.md): openrail is a control plane, an agent on every host, and Caddy, a registry and BuildKit run as containers by the agent.
- [Security model](https://openrail.app/docs/reference/security-model.md): How openrail protects the console, the hosts, your secrets and your builds.
- [Ports and firewall](https://openrail.app/docs/reference/ports-firewall.md): The ports openrail needs open, and the firewall rules it manages on each host.
- [Limits](https://openrail.app/docs/reference/limits.md): The numbers openrail v0.1 is built and tested for.
- [Honest limits](https://openrail.app/docs/reference/honest-limits.md): What openrail v0.1 does not do, said plainly, with what to do about each one.

## Templates

- [MongoDB](https://openrail.app/https://openrail.app/docs/databases/mongodb.md): Document database with daily compressed dumps.
- [MySQL](https://openrail.app/https://openrail.app/docs/databases/mysql.md): The popular relational database. Backups are not supported yet.
- [Postgres with pgvector](https://openrail.app/https://openrail.app/docs/databases/pgvector.md): Postgres with the pgvector extension for embeddings and similarity search.
- [Postgres with PostGIS](https://openrail.app/https://openrail.app/docs/databases/postgis.md): Postgres with PostGIS for geographic data.
- [Postgres](https://openrail.app/https://openrail.app/docs/databases/postgres.md): The open source relational database, with continuous backups and point-in-time restore.
- [Redis](https://openrail.app/https://openrail.app/docs/databases/redis.md): In-memory key-value store with append-only persistence.
- [Directus](https://openrail.app/https://openrail.app/docs/templates/directus.md): Headless CMS and data platform on Postgres, with Redis caching.
- [Ghost](https://openrail.app/https://openrail.app/docs/templates/ghost.md): Publishing platform for blogs and newsletters, backed by MySQL.
- [Gitea](https://openrail.app/https://openrail.app/docs/templates/gitea.md): Lightweight Git hosting with issues and pull requests, backed by Postgres.
- [Meilisearch](https://openrail.app/https://openrail.app/docs/templates/meilisearch.md): Fast, typo-tolerant search engine with a simple API.
- [Metabase](https://openrail.app/https://openrail.app/docs/templates/metabase.md): Business intelligence and dashboards, with its settings in Postgres.
- [MinIO](https://openrail.app/https://openrail.app/docs/templates/minio.md): S3-compatible object storage with a web console.
- [n8n](https://openrail.app/https://openrail.app/docs/templates/n8n.md): Workflow automation you host yourself, backed by Postgres.
- [Plausible CE](https://openrail.app/https://openrail.app/docs/templates/plausible.md): Lightweight, cookie-free web analytics with Postgres and ClickHouse.
- [Umami](https://openrail.app/https://openrail.app/docs/templates/umami.md): Simple, privacy-focused web analytics, backed by Postgres.
- [Uptime Kuma](https://openrail.app/https://openrail.app/docs/templates/uptime-kuma.md): Self-hosted uptime monitoring with status pages.

## CLI

- [CLI overview](https://openrail.app/docs/cli/overview.md): The `openrail` CLI deploys, inspects and manages your services from a terminal or CI, and also answers to `railway`.
- [Global options](https://openrail.app/docs/cli/global-options.md): Every `openrail` command accepts the same options for picking a project, environment and service, for JSON output and for skipping prompts.
- [The railway alias](https://openrail.app/docs/cli/railway-alias.md): The `openrail` binary also answers to `railway`, so scripts and habits built on Railway's CLI keep working.
- [openrail login](https://openrail.app/docs/cli/login.md): Log the CLI in to an openrail console and store an API token.
- [openrail logout](https://openrail.app/docs/cli/logout.md): Remove the stored token for the current console.
- [openrail whoami](https://openrail.app/docs/cli/whoami.md): Print the user and console the CLI is logged in to.
- [openrail init](https://openrail.app/docs/cli/init.md): Create a project and link this directory to it.
- [openrail link](https://openrail.app/docs/cli/link.md): Link this directory to a project, environment and service.
- [openrail unlink](https://openrail.app/docs/cli/unlink.md): Remove the link between this directory and a project.
- [openrail status](https://openrail.app/docs/cli/status.md): Show the linked project, environment and service, with its status and URL.
- [openrail list](https://openrail.app/docs/cli/list.md): List the projects you can see.
- [openrail open](https://openrail.app/docs/cli/open.md): Open the project canvas in your browser.
- [openrail up](https://openrail.app/docs/cli/up.md): Upload this directory and deploy it into the linked service, streaming the logs.
- [openrail redeploy](https://openrail.app/docs/cli/redeploy.md): Redeploy the active deployment of the linked service.
- [openrail restart](https://openrail.app/docs/cli/restart.md): Restart the active deployment's containers, one replica at a time.
- [openrail down](https://openrail.app/docs/cli/down.md): Remove the active deployment of the linked service.
- [openrail deploy](https://openrail.app/docs/cli/deploy.md): Add a template to the linked project and deploy it.
- [openrail templates](https://openrail.app/docs/cli/templates.md): List or search the templates this install ships.
- [openrail add](https://openrail.app/docs/cli/add.md): Add a service: a database, a GitHub repo, a Docker image or an empty service.
- [openrail import](https://openrail.app/docs/cli/import.md): Import a Railway project, a Docker Compose file or Heroku variables.
- [openrail logs](https://openrail.app/docs/cli/logs.md): Print deploy, build or HTTP logs, following them on a terminal.
- [openrail variables](https://openrail.app/docs/cli/variables.md): List, set and delete the linked service's variables.
- [openrail run](https://openrail.app/docs/cli/run.md): Run a local command with the service's resolved variables.
- [openrail shell](https://openrail.app/docs/cli/shell.md): Open a local subshell with the service's variables loaded.
- [openrail ssh](https://openrail.app/docs/cli/ssh.md): Open a shell inside a running replica.
- [openrail connect](https://openrail.app/docs/cli/connect.md): Open psql, mysql, redis-cli or mongosh against a database through a local tunnel.
- [openrail domain](https://openrail.app/docs/cli/domain.md): Generate a domain or add a custom domain for the linked service.
- [openrail tcp-proxy](https://openrail.app/docs/cli/tcp-proxy.md): Expose a TCP port of the linked service on a public port.
- [openrail environment](https://openrail.app/docs/cli/environment.md): Switch, create, sync and inspect environments.
- [openrail service](https://openrail.app/docs/cli/service.md): Switch the linked service or change a service.
- [openrail scale](https://openrail.app/docs/cli/scale.md): Set the number of replicas for the linked service.
- [openrail volume](https://openrail.app/docs/cli/volume.md): List, add, delete or wipe the linked service's volume.
- [openrail cron](https://openrail.app/docs/cli/cron.md): List cron runs of the linked service or start one now.
- [openrail metrics](https://openrail.app/docs/cli/metrics.md): Print CPU, memory, network and HTTP summaries for the linked service.
- [openrail usage](https://openrail.app/docs/cli/usage.md): Show resource usage for a period and what it would cost on Railway.
- [openrail config](https://openrail.app/docs/cli/config.md): Export an environment's services and settings to a file.
- [openrail host](https://openrail.app/docs/cli/host.md): Add, list, drain and maintain hosts.
- [openrail upgrade](https://openrail.app/docs/cli/upgrade.md): Upgrade the install: the control plane first, then each agent.
- [openrail alias](https://openrail.app/docs/cli/alias.md): Install or remove the `railway` symlink to this CLI.
- [openrail completion](https://openrail.app/docs/cli/completion.md): Print a shell completion script.
- [openrail version](https://openrail.app/docs/cli/version.md): Print the CLI version.

## Compare

- [openrail and Railway](https://openrail.app/docs/compare/railway.md): Railway is a managed platform; openrail brings its workflow to servers you run, with trade-offs in both directions.
- [openrail and Coolify](https://openrail.app/docs/compare/coolify.md): Coolify is a popular self-hosted panel; openrail differs in its Railway-style canvas, references between services and built-in multi-host load balancing.
- [openrail and Dokploy](https://openrail.app/docs/compare/dokploy.md): Dokploy runs on Docker Swarm; openrail runs its own agent on plain Docker with a WireGuard mesh and needs no external registry.
- [openrail and Kamal](https://openrail.app/docs/compare/kamal.md): Kamal deploys containers from your laptop or CI over SSH; openrail is a running platform with a console, databases and backups.
- [openrail and Dokku](https://openrail.app/docs/compare/dokku.md): Dokku is a long-standing single-host Heroku-style tool driven by git push and a CLI; openrail adds a web canvas and multi-host replicas.
- [openrail and a plain VPS](https://openrail.app/docs/compare/vps.md): Running apps on a VPS by hand is cheapest in software but costs time; openrail automates the parts that take it.

## Contribute

- [Building from source](https://openrail.app/docs/contribute/build-from-source.md): Build the control plane, the agent, the CLI, the console and this site from a clone of the repo.
- [The Makefile](https://openrail.app/docs/contribute/makefile.md): Every routine task in the repo is a `make` target; `make help` lists them.
- [Writing a template](https://openrail.app/docs/contribute/writing-a-template.md): A template is a directory in `templates/` with a manifest that describes the services to create, their images, volumes, variables and inputs.