Documentation

Start with the Quick start.

Get started

• Quick start: Install 5050cloud on a Linux VM, open the console, deploy a GitHub repo and add Postgres in about five minutes.
• The basics: 5050cloud organises your apps into projects, environments, services and deployments, the same way Railway does, and runs them on hosts you own.
• Coming from Railway: 5050cloud follows Railway names, variables and config files, so most projects move over unchanged; this page lists every difference in v0.1.
• Production checklist: Work through this list before you put real traffic on a 5050cloud install.

Guides

• Deploy from GitHub: Connect a GitHub repo to a service and 5050cloud builds and deploys every push to its branch.
• Deploy a Docker image: 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: `5050 up` uploads the current directory, builds it on your hosts and streams the logs until the deploy is live.
• Config as code: Keep a service's build and deploy settings in your repo with `railway.json`, `railway.toml`, `5050.yaml` or `5050.json`.
• Import from Railway: Bring a whole Railway project over as staged changes: services, sources, settings, variables, domains, volumes and databases.
• Move a database from Railway: Copy a database from Railway into a 5050cloud database service with one pipe through `5050 connect`.
• Import Docker Compose: Turn a `docker-compose.yml` into services on the canvas, staged for you to review before anything deploys.
• Templates and the Deploy on 5050cloud button: Deploy ready-made apps such as n8n, Umami or Uptime Kuma in one click, and add a Deploy on 5050cloud button to your own README.
• Add Postgres, MySQL, Redis or MongoDB: Add a database in one click; it gets a volume, generated credentials and the same variable names Railway uses.
• Variables and references: Set environment variables per service, share them across an environment, and reference other services with `${{Service.VAR}}`.
• Staged changes and environment sync: 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: Every service can have a generated domain and your own domains, each with an automatic Let's Encrypt certificate.
• Use all cores: Run one process per vCPU in each replica so single-threaded runtimes like Node use every core of the host.
• Add a host: Join another Linux VM with one command to run more replicas, databases or builds, or to add a second public entry point.
• Replicas and zero-downtime deploys: Run several replicas of a service across your hosts and deploy new versions without dropping requests.
• Health checks: A health check tells 5050cloud when a new deployment is ready for traffic and when a running replica should be taken out of routes.
• Rollbacks: Roll back to an earlier deployment and get its exact image and the variables it ran with.
• Cron jobs: Run a service on a schedule instead of keeping it running.
• Volumes: Give a service persistent storage that survives deploys and restarts.
• Backups and restore to a copy: 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: Move a database to a new major version by restoring a dump into a copy, then promoting it.
• Monorepos and watch paths: Deploy several services from one repo, each from its own directory, and build only the ones whose files changed.
• Pre-deploy migrations: Run a command such as a database migration before each new version starts serving.
• Private networking: Services in one environment reach each other by name over a private network that spans every host.
• Quarantined environments: Block outbound internet traffic from an environment, with an allowlist, while its private network keeps working.
• Monitors and alerts: Get an email or webhook when a service's CPU, memory, disk or error rate stays above a threshold.
• Email and notifications: Send password resets, invites and alerts by email, choose which events reach you, and receive signed webhooks.
• Members, roles and 2FA: Invite people with a role, limit them per project, and require two-factor authentication.
• Upgrading and host maintenance: Upgrade 5050cloud with one command that reverts itself if the new version is unhealthy, and take hosts out for OS work without downtime.
• Backing up the control plane: The control plane keeps all projects, settings and encrypted variables in one database that is snapshotted hourly and, with a bucket, streamed continuously.
• Rebuild the control host: If the control host is lost, install on a new VM with `--restore` and the cluster comes back from your bucket.
• Rotate the master key: Replace the key that encrypts every secret in the control plane, for example after someone with host access leaves.
• Behind Cloudflare: Proxy your domains through Cloudflare while 5050cloud keeps issuing certificates and sees real client IPs.
• Troubleshooting failed deploys: Every failed or crashed deployment shows one sentence that names the cause; this page explains each one and what to do.

Reference

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

Templates

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

CLI

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

Compare

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

Contribute

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