43 guides · synced daily from GitHub
Homerun docs
A single-host PaaS. 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, single-user PaaS for deploying Docker containers with a click-config form: a minimal Dokploy / Cloud Run alternative for your own hardware.
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. There is 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 (admin-only) 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.
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.
Services
Sources, builds, deploys, networking and runtime for a single service.
Services
A service is one deployed container. Create one from Services → New, 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.
Git providers
1. An admin 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. To give it more repositories later, change the installation on GitHub. 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 on the Source tab (or in the wizard) and every push to the service's branch deploys it, as its owner, without you touching the dashboard.
PR previews
Tick Pull request previews on a git service's Source tab and every pull request opened on its repo gets a service of its own, <slug>-pr-<number> (so <slug>-pr-<number>.<baseDomain>), built from the pull request's head and deployed as the service's owner. Each push to the pull request redeploys the preview; closing or merging it deletes the preview, container, DNS records and all. GitHub, Gitea and GitLab previews build the exact head commit; Bitbucket only sends an abbreviated hash, so its previews build the head branch, which covers every pull request previews are made for anyway.
Required status checks
A git-mode service can refuse to build until its CI agrees. On the Source tab, 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 (admin-only) 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/Start/Stop/Restart 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 and the ones that reference it, and a tail of its live logs. Deployment history, every attempt with its status, image and full log, is on the Revisions tab.
Revisions and rollback
Every deploy that reaches running is a revision: the exact image it ran (image:tag plus the registry digest when there is one, or the local homerun-build-<slug>:<tag> for a git build), the commit and branch for a git build, and whether it stayed healthy. The Revisions tab lists them with the current one marked, next to failed attempts and their logs.
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.
Env vars
Plain key/value rows on the Env Vars tab, 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.
DNS automation
If your instance's DNS is on Cloudflare, or you front it with a self-hosted Pangolin tunnel instead, configure one (or both) from /settings → Networking and Homerun keeps DNS in sync on its own for any service with DNS-resolvable on: a deploy creates or updates a record per routed hostname (a Cloudflare CNAME, or a Pangolin Resource + Target), deleting the service removes them, including any extra domains it has.
Runtime and compute
How a service's container starts, what it can reach on the host, and how much CPU and memory it gets.
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 the Compute tab 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.
Observability
The Observability tab is where a service tells you whether it's healthy: uptime probes, live logs, failed deploys and the errors Homerun logged about it.
Scheduling and the job queue
Everything that runs on a timer or in the background: scheduled redeploys, cron jobs, the Scheduling page that lists them, and the job queue behind all of it.
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 stack also prefixes its member services' public subdomains: <stackSlug>-<slug>.<baseDomain>.
Templates
A template is a saved service config (image, tag, container port, env vars, CPU/ memory, and the runtime options: entrypoint, command, labels, 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) is a named source you define once, then mount into one or more services from each service's Volumes tab:
S3 backups
Back up storage volumes to any S3-compatible bucket, on a schedule or on demand, and restore them from the dashboard.
Build servers & agent
Services always deploy to this host's own Docker daemon. Placement across machines is swarm mode's job: a second machine joins the swarm as a worker (cmd/installer/swarm-join.sh) rather than being registered separately.
Users and access
Accounts, roles, sign-in methods and protecting your apps.
Users and roles
Homerun has three roles, admin, developer and read-only. Every account sees every resource on the instance, and every admin or developer account manages it: services, stacks, volumes, backups, S3 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. Between admin and developer, the only difference is a few admin-only pages, Users, Authentication, Settings, System Logs and Docker Cleanup (see Docker Cleanup), plus admin-only actions elsewhere: registering a git provider's OAuth app and host-command cron jobs. There's no finer-grained permission system yet (no per-stack access control, no teams).
Authentication providers
The Authentication page (Administration, admin-only) is where sign-in methods are configured for the whole instance:
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.
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
The Search… button in the header, or ⌘K / Ctrl+K anywhere, opens a command palette. It jumps to any dashboard page by name, and once you've typed two characters it also searches the instance's services, stacks, templates, cron jobs, storage volumes, S3 destinations, remote hosts, build cache registries, git providers, notification channels and status pages, plus users and authentication providers for an admin.
System Logs
This instance's stack lists every container your compose file starts, Homerun itself, Postgres and Traefik included, with its state. Click one to open its live log. Traefik's is where routing problems show up: a service that deployed fine but returns 404, a certificate that won't issue, a middleware that isn't attaching. The list only appears when Homerun runs as a Docker Compose service; run from source, the app's own output is whatever your terminal or process manager is already capturing.
Docker Cleanup
The page previews what's actually reclaimable before you commit, unused images, stopped containers, unreferenced volumes, unused networks (excluding Docker's own three defaults and anything still attached), and unused build cache, with the space each category would free. You can then prune each category on its own, or use Quick cleanup → Clean up now, which prunes stopped containers, dangling images, unused networks and build cache together, the same set as docker system prune, and never touches volumes. Every action asks for confirmation first.
Notifications
The bell in the header is 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 auto-redeploy firing, an image scan finding a critical vulnerability, and runtime errors attributed to a service. Click an entry to jump to its service, mark everything read from the dropdown, or hover a row and use the x to drop it.
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 also see a notice there when a newer GitHub release exists (checked every ten minutes). Clicking it opens the update dialog:
API & CLI
An API key is created with Full access or Read-only access (see API keys). A read-only key, or any request from a read-only account, can call every GET endpoint; every POST, PATCH and DELETE answers 403 with {"error": "This account or API key is read-only: ..."}. The OpenAPI spec lists that 403 on every write.