62 guides · synced daily from GitHub
Homerun docs
A self-hosted PaaS that starts on one box. Point it at an image or a git repo, fill a form, hit deploy, and Traefik routes it with TLS. No Kubernetes anywhere near it.
Introduction
A self-hosted PaaS that starts on one box. Swarm workers when you want more. No Kubernetes, no separate control plane. Deploy Docker containers with a click-config form, a Dokploy / Cloud Run alternative for your own hardware, for you alone or a whole team. MIT licensed.
Contributing
This is the "I want to run this from source and change code" guide. If you just want to run Homerun, you don't need any of this: use the installer one-liner or compose.prod.yaml instead, see docs/getting-started.md. Nothing here (git, Bun, a dev server) is needed for either of those paths.
Getting started
Install, first boot, first deploy.
Getting started
Homerun needs three things at runtime: a Docker socket to manage containers, a Postgres database, and Traefik for routing and TLS. Pick whichever install path fits, both run entirely from prebuilt release binaries and Docker images, and neither needs Bun, git, or a source checkout on the target host. Want to run from source instead, to develop on it? See CONTRIBUTING.md.
Showcase
Every screenshot below is generated by driving a real instance with Playwright (bun run screenshots): a blank database, a real sign-up, the onboarding wizard, then a stack with three services, two of them actually deployed as containers on the host's Docker socket, and real HTTPS traffic sent through a real Traefik to one of them. No demo instance to keep alive and no hand-retouched marketing shot: if a screen stops rendering, the run fails rather than publishing it.
Configuration
Almost everything is a setting in the dashboard. The first-run wizard asks for what a first deploy needs, and /settings (needs the Settings permission, admins have it) lets you change any of it later, live, with no restart and no file to edit. If you installed with the one-liner, that's the whole story: it set the handful of values the container itself needs before it can start, and everything after that is the UI.
Simple and advanced modes
The dashboard runs in one of two modes.
FAQ
Homerun is new. If you're used to another self-hosted PaaS, most of what you expect is here, but some things work differently and a few aren't built yet. This page is the honest list, so you find out here rather than halfway through moving your services over.
Architecture
What runs where, who talks to whom, over what, and why. It's the map to read before debugging a request that crosses two processes, or before adding a new integration.
Services
Sources, builds, deploys, networking and runtime for a single service.
Services
A service is one deployed container. Create one from Services → Deploy a Service, either standalone or pre-filled from a stack or template via ?stackId=/?templateId=. The wizard's primary button, Create and Deploy, persists the config and immediately deploys it, landing you on the new service's Overview tab; Create service, the secondary button, just persists the config, the same as before, deploy later from the Overview tab yourself.
Source and builds
Where a service's image comes from, how a git-based service is built, and which machine builds it.
Homerun Manifest
A Homerun Manifest is a service's configuration kept as a file: its port, environment, resources, health check, build method, domains, login wall, previews and so on. Commit it to the repository as .homerun.json (or .homerun.yaml / .homerun.yml, same keys) and every deploy of a service built from that repository applies it before building. Or apply it to any service, image-based ones included, with the CLI or the REST API.
Git providers
1. Someone with write access to Git providers registers the provider, once. For GitHub, give the app a name (and an organization, or leave it empty for your personal account) and click Create GitHub App: GitHub asks you to confirm the app, then to install it on the repositories Homerun should see. Nothing to copy by hand. The app only asks for what Homerun uses: read access to code, commit statuses and checks, and write access to repository webhooks, pull requests and deployments (the last two for pull request previews). To give it more repositories later, change the installation on GitHub. An app created before previews reported to GitHub lacks the pull request and deployment permissions, and GitHub answers "Resource not accessible by integration": in the app's settings on GitHub, under Permissions, give it Read and write on Pull requests and Deployments, save, then accept the new permissions on its installation (Settings → Applications → Installed GitHub Apps → Configure). Reconnecting isn't needed. A repo that already has Homerun's webhook (from a deleted app or an earlier connection) keeps it: Homerun takes it over and updates its secret and events instead of adding a second one, which GitHub and Gitea refuse. For GitLab, self-hosted Gitea (which also wants its base URL) or Bitbucket, register an OAuth application on that provider's own site and paste the client id and secret in. The page prints the exact callback URL to register on the provider's side. 2. Each person connects their own account from the same page, one click through the provider's consent screen. Connections are per-account: your token is yours, and another user connecting to the same provider gets their own.
Deploy on push
Turn on Deploy on push in the service's Environments & Deployments → Source section (or in the wizard) and every push to the service's branch deploys it, as its owner, without you touching the dashboard.
Deploying from CI
Deploy on push covers a service Homerun builds from git. When your CI builds and pushes the image itself (tests first, a registry of your own, a monorepo that builds several images), let the pipeline tell Homerun when to deploy instead: a GitHub Action, a Docker image for GitLab or any other CI, or one API call.
PR previews
Advanced mode: simple mode hides the Previews section of a service's Environments & Deployments tab. Everything here keeps working either way, and a hidden page still opens from a link.
Environments
Advanced mode: simple mode hides the Environments list on a service's Environments & Deployments tab. Everything here keeps working either way, and a hidden page still opens from a link.
Release channels
Advanced mode: simple mode hides the Channels section of a service's Environments & Deployments tab. Everything here keeps working either way, and a hidden page still opens from a link.
Canary and stable cookbook
A cookbook for one release model: every merge to main goes live on a canary site, and cutting a version tag (v1.4.0) ships it to the real one. Homerun does the routing with release channels; your CI only has to push tags.
Testing PRs with Actions
A cookbook: every pull request gets a real deployment of its own (a pull request preview), GitHub Actions runs your end-to-end suite against it, and shipping the pull request deploys the exact image that passed to production instead of rebuilding it. Three workflows:
Required status checks
A git-mode service can refuse to build until its CI agrees. In the service's Environments & Deployments → Source section, tick Require status checks to pass before building and pick the checks that must pass. The picker lists every check name reported on the latest commits of the service's branch, read live from the git provider: GitHub check runs and commit statuses, GitLab job statuses plus the pipeline itself (as pipeline), Gitea/Forgejo commit statuses, and Bitbucket build statuses (by key). A check that hasn't run recently can be added by name.
Compose import
Import compose on the services list takes a docker-compose.yaml pasted straight in and turns it into Homerun rows. Parsing happens on the server and nothing is created until you confirm: the preview lists every service it found with the image, port, protocol, network mode, env var count and volume mounts it resolved, plus a warning for anything it had to drop.
Migrating
Settings → Migrate (needs the Settings permission) reads another PaaS instance and recreates what it finds here. Pick Dokploy or Coolify, give it the instance URL and an API token, and Read instance lists every application, compose stack and database, grouped by the project it lives in. It only ever makes read requests: nothing on the other side is stopped, changed or deleted, and the token is sent with each request on that page, never stored.
Deploying
The Overview tab has Deploy (Rebuild for a git service), Start/Stop, Restart and, depending on the service, Fresh build (a git rebuild that ignores every cached layer), Pull image (pulls the configured image and tag without redeploying, and tells you whether it changed) and Kill (SIGKILLs a standalone container with no grace period; swarm services only get Stop), plus a live progress panel. The panel shows six phases, resolving configuration, preparing volumes, fetching image, provisioning container, routing traffic, ready, ticking off as they complete, with the raw build/pull output streaming underneath. Progress arrives over server-sent events (the server pushes each new line and status change; if that stream can't be held open, the panel falls back to polling), and it resumes correctly if you reload the page mid-deploy, or if the deploy was started somewhere else entirely (a template quick-deploy, cron). Below it sit a Resource usage chart for the service's own container (CPU, memory and network traffic, live or over the last hour, day, week, month, year or all of it, sampled every minute), a Connections panel listing the services it references through env vars or depends on through a service link, and the ones that reference or depend on it (same detection as a stack's dependency graph, see Stacks), each with an Unlink button (see Env vars), and a tail of its live logs. Deployment history, every attempt with its status, image and full log, is under Environments & Deployments → Revisions.
Revisions and rollback
Advanced mode: simple mode hides the Revisions section and the Deployments sidebar entry, and puts a Roll back to the previous version button on the service's Overview instead. Everything here keeps working either way, and a hidden page still opens from a link.
Image scanning
Every deploy scans the image for known vulnerabilities with Trivy before the workload starts. It's on by default and never enforced unless you ask for it.
Environment variables
Plain key/value rows under a service's Environments & Deployments → Environment Variables, stored as-is (not encrypted, don't put a raw plaintext secret you'd mind leaking in the DB dump into an env var if you can avoid it; registry passwords and similar have their own encrypted fields instead).
Networking
Everything on this tab is written onto the container as Traefik labels at create time, so saving a change here doesn't affect the container that's already running. Once a service has been deployed, the tab shows a Redeploy button for exactly that reason, use it after changing a domain or DNS-resolvability. The per-app login wall lives on the Security tab.
Redirects
Redirects (sidebar, Infrastructure) sends a hostname, or a path under one, to another URL. Traefik answers the request itself, no container is involved.
Error pages
Traefik's own errors are a bare 404 page not found or Bad Gateway. Homerun replaces them with a branded page, so a visitor who arrives early or while an app is down sees something that says what's going on.
DNS automation
The DNS page (sidebar → Integrations, needs the DNS permission) is where Homerun manages your domains' DNS. It has three tabs: Domains, Providers and Pangolin.
Runtime and compute
Advanced mode: simple mode hides the Runtime section of a service's Container tab. Everything here keeps working either way, and a hidden page still opens from a link.
Swarm mode
Instance-wide (/settings → Docker → Orchestration mode), and what the one-line installer sets up: the installer makes the system Docker daemon a swarm manager, and a brand new instance on a rootful swarm manager starts in swarm mode (an existing instance keeps whatever mode it has, and a rootless or non-swarm daemon starts in standalone). In swarm mode every local deploy creates a real Docker Swarm Service instead of a plain container, and Container → Compute gets a replicas field (default 1) controlling how many copies Docker runs and load-balances across via its own routing mesh. Start/ stop map to scaling to 0/back up rather than a real container stop/start, and restart force-updates every task (recreating them) instead of restarting one container. Restart reuses the service's current settings: a changed environment variable needs a Deploy.
Observability
The Observability tab is where a service tells you how it's doing. It has six sections: Monitoring, its traffic, response time, error rate, uptime and resource use over a range; Events, its uptime probes, live logs, failed deploys and the errors Homerun logged about it; Errors, the exceptions your app reports (see Error tracking); Traces, its OpenTelemetry traces (see Tracing); Pipelines, the CI runs of the repository linked to it (see Pipelines); and Health, the healthcheck the running container was created with (see Services).
Error tracking
Advanced mode: simple mode hides the Errors section of a service's Observability tab. Everything here keeps working either way, and a hidden page still opens from a link.
Tracing
Advanced mode: simple mode hides the Traces section of a service's Observability tab and the Traces tab of Monitoring. Everything here keeps working either way, and a hidden page still opens from a link.
Pipelines
Pipelines, under Observability in the sidebar, brings the CI runs of the repositories you choose into Homerun: GitHub Actions workflow runs, GitLab CI pipelines and Gitea Actions runs (Gitea 1.24 or later, the first version with an Actions API). Each run lands with its jobs, timings and an estimated cost, the pages add them up, and every finished run becomes a trace you can open as a waterfall. Bitbucket Pipelines isn't supported.
Scheduling and the job queue
Advanced mode: simple mode hides the Scheduling sidebar entry. Everything here keeps working either way, and a hidden page still opens from a link.
Stacks, templates and storage
Grouping services, the app catalog, volumes, backups and build servers.
Stacks
A stack groups services together and gives them a shared, private Docker network, member services can reach each other by plain slug (http://api:8080), separate from the shared homerun every service also joins for Traefik routing. A service created inside a stack, from the wizard or from a template, also gets the stack's slug as a prefix by default: Redis created in stack vortex becomes vortex-redis, routed at vortex-redis.<baseDomain>; that prefix isn't added a second time on top of an already-prefixed slug.
Templates
A template is a saved service config (image, tag, container port, env vars, CPU/ memory, and the runtime options: entrypoint, command, labels, run-as user, env files, added capabilities, devices and privileged mode) you can deploy from repeatedly without re-entering everything. Two kinds:
Storage volumes
A storage volume (/storage, Volumes under Storage in the sidebar) is a named source you define once, then mount into one or more services from each service's Storage tab:
Volume backups
Back up storage volumes to an S3-compatible bucket, an SFTP server, an SMB share or a WebDAV server, on a schedule or on demand, and restore them from the dashboard.
Object storage
Object Storage (needs the Object storage permission, under Storage in the sidebar) gives you S3 buckets without paying for a cloud: a built-in object store Homerun runs for you, plus any S3-compatible provider you connect, side by side. The page has three tabs: Buckets, Stores and Built-in. Terraform state kept in these buckets is managed from Infrastructure as code.
Build servers & agent
Advanced mode: simple mode hides the Remote Hosts and Build Cache sidebar entries. Everything here keeps working either way, and a hidden page still opens from a link.
Workstations
Workstations in the sidebar (Workspace) gives you a dev box in the browser: a container running a web IDE (code-server by default, VS Code in the browser, or openvscode-server) with a home directory that survives restarts and, optionally, your repository already cloned into it. It runs on this server, on any agent host, or on a remote Docker host registered with a tcp:// or ssh:// address.
Machine terminals
Advanced mode: simple mode hides the Terminal sidebar entry. Everything here keeps working either way, and a hidden page still opens from a link.
Users and access
Accounts, roles, sign-in methods and protecting your apps.
Users and roles
Homerun has five roles, admin, developer, read-only, app access only and custom. Every dashboard account sees the same pool of resources, and what an account may do with it is decided by its permissions. Services, stacks, volumes, backups, backup destinations, build cache registries, remote hosts, cron jobs, status pages, custom templates and the job queue are shared, whoever created them. Each one still records who created it. What stays personal is your sessions, API keys, preferences, git provider connections, terminal sessions, bell feed and notification channels. Every account gets a copy of each bell notification, and every account's own notification channels hear about every event. Homerun has no teams and no per-stack access control: permissions are per area of the dashboard, not per resource.
Authentication providers
The Authentication page (Administration, needs the Users & authentication permission) is where sign-in methods are configured for the whole instance. It has three tabs: Sign-in (built-in accounts, preferred methods and requirements), Providers and Protected apps (every service behind the login wall and the methods it accepts). Homerun as a provider for your own apps has its own IDP page, see Sign in with Homerun.
Your profile
The profile pages (reached from the avatar menu, not the sidebar) are per account:
2FA and passkeys
Both live under Profile → Security.
Login wall
A deployed service can require a login before anyone reaches it. Turn on Require login to access this app on the service's Security tab, under Login wall, or in the deploy wizard's Networking step. Turning it on in the wizard enables the built-in Homerun login as the sign-in method; add OAuth providers or an allow-list on the Security tab afterwards.
Blocked paths and IP bans
Advanced mode: simple mode hides the Blocked paths panel (unless the service already blocks paths) and the IP bans settings tab. Everything here keeps working either way, and a hidden page still opens from a link.
Sign in with Homerun
Homerun is also an OpenID Connect (OIDC) provider. Apps you host can offer "Sign in with Homerun" using the same accounts as the dashboard, so you don't need to run Pocket ID, Authentik or Keycloak just to give Grafana or Outline a login. Whatever the dashboard requires (passkeys, two-factor codes, your preferred sign-in methods) applies to these sign-ins too.
Operations and maintenance
Keeping the instance healthy, informed and up to date.
The dashboard
Every list page (services, stacks, templates, cron jobs, storage, remote hosts, build cache registries, backup destinations, users) has the same toolbar: a search box, a sort (newest, oldest, name A–Z or Z–A, recently updated, and most services on stacks), filters where the list has any, and a pager. All of them run on the server over everything you can see, and live in the URL.
System Logs
Advanced mode: simple mode hides the System Logs sidebar entry. Everything here keeps working either way, and a hidden page still opens from a link.
Docker Cleanup
Advanced mode: simple mode hides the Docker Cleanup sidebar entry. Everything here keeps working either way, and a hidden page still opens from a link.
Docker Registry
Advanced mode: simple mode hides the Registry sidebar entry. Everything here keeps working either way, and a hidden page still opens from a link.
Notifications
The bell in the header opens Notifications, a per-account feed of lifecycle events on every service, whoever created it (each account gets its own copy to read and clear): deploy succeeded or failed, a build stopped by status checks, an unhealthy or rolled back revision, service created, started, stopped, an image scan finding a critical vulnerability, and runtime errors attributed to a service, plus the server crossing a resource limit. The bell shows how many are unread. Click an entry to jump to its service and mark it read, use Mark all read, drop one with its x, or Clear all.
Status pages
Status Page in the sidebar builds an uptime page out of your services' uptime probes. Each page has a name, a slug and an optional description, and covers one of three sets: every service, one stack, or services you pick. Its page in the dashboard shows each service's recent heartbeats and uptime percentage.
Upgrading Homerun
The sidebar shows the version you're running. Admins can click it any time to open an update-status dialog; a notice also appears there on its own when a newer GitHub release already exists (checked every ten minutes). A Check for updates button inside the dialog bypasses that ten-minute cache and asks GitHub right away. Once an update is available, the dialog behaves as follows:
API & CLI
Every route belongs to one permission area (services, stacks, DNS and so on): a GET needs read access to it, a POST, PATCH or DELETE needs write access. A request from an account or API key without it answers 403 with an error naming the area, such as {"error": "You don't have permission to change Services."}. An API key is created with the permissions you pick, an expiry and, optionally, "all permissions" (see API keys), and is always limited to what its owner holds at that moment. A banned account's keys are refused with a 403 until the ban is lifted or runs out. Profile, CLI login, the API docs and the MCP endpoint are open to any signed-in account. An API key makes up to 3000 requests a minute; past that it gets 429 Too Many Requests with a Retry-After header (in seconds) until the minute is up. The OpenAPI spec lists that 403 on every route.
MCP server for AI agents
Homerun serves an MCP server, so an AI agent such as Claude can diagnose and fix your services for you: read their logs, deploys and settings, change them, redeploy, roll back.
Infrastructure as code
Homerun can be managed with Terraform, OpenTofu or Pulumi: stacks, services and every setting the dashboard has, plus the objects around them. The Infrastructure as Code page (Integrations, needs the Infrastructure as code permission) lists your IaC projects. Each project picks a tool, keeps its state in a bucket on one of your object stores, covers a stack or a service, writes a starter configuration from what's already running and compares its state with the instance to show what changed outside it.