Install on a VM

Documentation

Install openrail on a VM, deploy your first service, and look up every setting, command and endpoint. Every page is also plain Markdown, listed in llms.txt.

Read the quick start Coming from Railway Honest limits

Get started

  • Quick startInstall openrail on a Linux VM, open the console, deploy a GitHub repo and add Postgres.
  • The basicsopenrail organises your apps into projects, environments, services and deployments, the same way Railway does, and runs them on hosts you own.
  • Coming from Railwayopenrail follows Railway names, variables and config files, so most projects move over unchanged; this page lists every difference in v0.1.
  • Production checklistWork through this list before you put real traffic on an openrail install.

Set up

  • InstallInstall openrail on a fresh Linux VM with one command, or walk through a guided setup that asks for your domain and email.
  • Your domainsServe the console and your services' generated names from your own domain instead of sslip.io, at install time or later.
  • FirewallOpen only the ports openrail needs, with your cloud provider's firewall, the installer's --firewall rules, or ufw.
  • Email (SMTP)Connect an SMTP server so invites, password resets, email verification and alerts go out by email.
  • GitHub AppCreate a GitHub App for your install so openrail can read private repos and deploy on every push, without copying keys by hand.
  • Backups bucketPoint 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 hostJoin another Linux VM with one command to run more replicas, databases or builds, or to add a second public entry point.
  • Cloudflare in frontProxy your domains through Cloudflare while openrail keeps issuing certificates and logs your visitors' real IP addresses.
  • The CLIInstall the openrail CLI on your laptop or in CI, log in to your console, and optionally make it answer to railway.
  • Members and invitesInvite people with a role, limit them per project, turn on two-factor authentication, and read the audit log.
  • UpgradesUpgrade openrail with one command that reverts itself if the new version is unhealthy, and take hosts out for OS work without downtime.
  • RestorePick 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 GitHubConnect a GitHub repo to a service and openrail builds and deploys every push to its branch.
  • Deploy a Docker imageRun any public or private Docker image as a service, with the same variables, domains and scaling as a built service.
  • Deploy with the CLIopenrail up uploads the current directory, builds it on your hosts and streams the logs until the deploy is live.
  • Config as codeKeep a service's build and deploy settings in your repo with railway.json, railway.toml, openrail.yaml or openrail.json.
  • Move a project from RailwayMove 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 RailwayCopy a database from Railway into an openrail database service with one pipe through openrail connect.
  • Import Docker ComposeTurn a docker-compose.yml into services on the canvas, staged for you to review before anything deploys.
  • Templates and the Deploy on openrail buttonDeploy 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 MongoDBAdd a database in one click; it gets a volume, generated credentials and the same variable names Railway uses.
  • Variables and referencesSet environment variables per service, share them across an environment, and reference other services with ${{Service.VAR}}.
  • Staged changes and environment syncEdits 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 HTTPSGive 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 coresRun one process per vCPU in each replica so single-threaded runtimes like Node use every core of the host.
  • Replicas and zero-downtime deploysRun several replicas of a service across your hosts and deploy new versions without dropping requests.
  • Health checksA health check tells openrail when a new deployment is ready for traffic and when a running replica should be taken out of routes.
  • RollbacksRoll back to an earlier deployment and get its exact image and the variables it ran with.
  • Cron jobsRun a service on a schedule instead of keeping it running.
  • VolumesGive a service persistent storage that survives deploys and restarts.
  • Backups and restore to a copyBack 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 upgradesMove a database to a new major version by restoring a dump into a copy, then promoting it.
  • Monorepos and watch pathsDeploy several services from one repo, each from its own directory, and build only the ones whose files changed.
  • Pre-deploy migrationsRun a command such as a database migration before each new version starts serving.
  • Private networkingServices in one environment reach each other by name over a private network that spans every host.
  • Quarantined environmentsBlock outbound internet traffic from an environment, with an allowlist, while its private network keeps working.
  • Monitors and alertsGet an email or webhook when a service's CPU, memory, disk or error rate stays above a threshold.
  • Email and notificationsSend password resets, invites and alerts by email, choose which events reach you, and receive signed webhooks.
  • Control plane backupThe 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 hostWhat 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 keyRotating 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 deploysEvery failed or crashed deployment shows one sentence that names the cause; this page explains each one and what to do.

Reference

  • Install optionsEvery flag of the installer, each also readable from a FIFTY_<FLAG> environment variable.
  • Service settingsEvery setting a service has, with its default and the Railway setting it matches.
  • Config file schemaThe fields railway.json, railway.toml, openrail.yaml and openrail.json accept, with what each one sets.
  • Variables referenceThe variables openrail provides to every replica, their Railway aliases, the reference syntax and the variables that change settings.
  • Deployment statusesThe labels a deployment shows on the card, in the panel, in the CLI and in webhooks, and what each one means.
  • Log filter syntaxFilter deploy, build and HTTP logs in the console and with openrail logs -f using Railway's filter syntax.
  • TemplatesThe database and app templates that ship with openrail v0.1.
  • APIThe openrail REST API serves everything the console and the CLI do, with the same roles and audit log.
  • Agent protocolAgents connect out to the control plane over one WebSocket and reconcile their host to the desired state they receive.
  • Architectureopenrail is a control plane, an agent on every host, and Caddy, a registry and BuildKit run as containers by the agent.
  • Security modelHow openrail protects the console, the hosts, your secrets and your builds.
  • Ports and firewallThe ports openrail needs open, and the firewall rules it manages on each host.
  • LimitsThe numbers openrail v0.1 is built and tested for.
  • Honest limitsWhat openrail v0.1 does not do, said plainly, with what to do about each one.

Templates

  • MongoDBDocument database with daily compressed dumps.
  • MySQLThe popular relational database. Backups are not supported yet.
  • Postgres with pgvectorPostgres with the pgvector extension for embeddings and similarity search.
  • Postgres with PostGISPostgres with PostGIS for geographic data.
  • PostgresThe open source relational database, with continuous backups and point-in-time restore.
  • RedisIn-memory key-value store with append-only persistence.
  • DirectusHeadless CMS and data platform on Postgres, with Redis caching.
  • GhostPublishing platform for blogs and newsletters, backed by MySQL.
  • GiteaLightweight Git hosting with issues and pull requests, backed by Postgres.
  • MeilisearchFast, typo-tolerant search engine with a simple API.
  • MetabaseBusiness intelligence and dashboards, with its settings in Postgres.
  • MinIOS3-compatible object storage with a web console.
  • n8nWorkflow automation you host yourself, backed by Postgres.
  • Plausible CELightweight, cookie-free web analytics with Postgres and ClickHouse.
  • UmamiSimple, privacy-focused web analytics, backed by Postgres.
  • Uptime KumaSelf-hosted uptime monitoring with status pages.

CLI

  • CLI overviewThe openrail CLI deploys, inspects and manages your services from a terminal or CI, and also answers to railway.
  • Global optionsEvery openrail command accepts the same options for picking a project, environment and service, for JSON output and for skipping prompts.
  • The railway aliasThe openrail binary also answers to railway, so scripts and habits built on Railway's CLI keep working.
  • openrail loginLog the CLI in to an openrail console and store an API token.
  • openrail logoutRemove the stored token for the current console.
  • openrail whoamiPrint the user and console the CLI is logged in to.
  • openrail initCreate a project and link this directory to it.
  • openrail linkLink this directory to a project, environment and service.
  • openrail unlinkRemove the link between this directory and a project.
  • openrail statusShow the linked project, environment and service, with its status and URL.
  • openrail listList the projects you can see.
  • openrail openOpen the project canvas in your browser.
  • openrail upUpload this directory and deploy it into the linked service, streaming the logs.
  • openrail redeployRedeploy the active deployment of the linked service.
  • openrail restartRestart the active deployment's containers, one replica at a time.
  • openrail downRemove the active deployment of the linked service.
  • openrail deployAdd a template to the linked project and deploy it.
  • openrail templatesList or search the templates this install ships.
  • openrail addAdd a service: a database, a GitHub repo, a Docker image or an empty service.
  • openrail importImport a Railway project, a Docker Compose file or Heroku variables.
  • openrail logsPrint deploy, build or HTTP logs, following them on a terminal.
  • openrail variablesList, set and delete the linked service's variables.
  • openrail runRun a local command with the service's resolved variables.
  • openrail shellOpen a local subshell with the service's variables loaded.
  • openrail sshOpen a shell inside a running replica.
  • openrail connectOpen psql, mysql, redis-cli or mongosh against a database through a local tunnel.
  • openrail domainGenerate a domain or add a custom domain for the linked service.
  • openrail tcp-proxyExpose a TCP port of the linked service on a public port.
  • openrail environmentSwitch, create, sync and inspect environments.
  • openrail serviceSwitch the linked service or change a service.
  • openrail scaleSet the number of replicas for the linked service.
  • openrail volumeList, add, delete or wipe the linked service's volume.
  • openrail cronList cron runs of the linked service or start one now.
  • openrail metricsPrint CPU, memory, network and HTTP summaries for the linked service.
  • openrail usageShow resource usage for a period and what it would cost on Railway.
  • openrail configExport an environment's services and settings to a file.
  • openrail hostAdd, list, drain and maintain hosts.
  • openrail upgradeUpgrade the install: the control plane first, then each agent.
  • openrail aliasInstall or remove the railway symlink to this CLI.
  • openrail completionPrint a shell completion script.
  • openrail versionPrint the CLI version.

Compare

  • openrail and RailwayRailway is a managed platform; openrail brings its workflow to servers you run, with trade-offs in both directions.
  • openrail and CoolifyCoolify 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 DokployDokploy runs on Docker Swarm; openrail runs its own agent on plain Docker with a WireGuard mesh and needs no external registry.
  • openrail and KamalKamal deploys containers from your laptop or CI over SSH; openrail is a running platform with a console, databases and backups.
  • openrail and DokkuDokku 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 VPSRunning apps on a VPS by hand is cheapest in software but costs time; openrail automates the parts that take it.

Contribute

  • Building from sourceBuild the control plane, the agent, the CLI, the console and this site from a clone of the repo.
  • The MakefileEvery routine task in the repo is a make target; make help lists them.
  • Writing a templateA template is a directory in templates/ with a manifest that describes the services to create, their images, volumes, variables and inputs.