> 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. > Source: https://orochibraru.com/homerun/canary/docs · Site index: https://orochibraru.com/llms.txt # Homerun documentation 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. The Markdown in [the project repo](https://github.com/orochibraru/homerun/tree/main/docs) is the source of truth; these pages are generated from it. - [Homerun](https://orochibraru.com/homerun/canary/docs/readme.md): 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… - [Contributing to Homerun](https://orochibraru.com/homerun/canary/docs/contributing.md): 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… - [Getting started](https://orochibraru.com/homerun/canary/docs/getting-started.md): 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… - [Showcase](https://orochibraru.com/homerun/canary/docs/showcase.md): 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… - [Configuration](https://orochibraru.com/homerun/canary/docs/configuration.md): 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… - [Simple and advanced modes](https://orochibraru.com/homerun/canary/docs/ui-modes.md): The dashboard runs in one of two modes. - [FAQ & limitations](https://orochibraru.com/homerun/canary/docs/faq-and-limitations.md): 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… - [Architecture](https://orochibraru.com/homerun/canary/docs/architecture.md): 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… - [Services](https://orochibraru.com/homerun/canary/docs/services.md): A service is one deployed container. Create one from Services → Deploy a Service, either standalone or pre-filled from a stack or template via… - [Deploy source and build methods](https://orochibraru.com/homerun/canary/docs/deploy-source-and-builds.md): Where a service's image comes from, how a git-based service is built, and which machine builds it. - [Homerun Manifest](https://orochibraru.com/homerun/canary/docs/manifest.md): 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… - [Connecting a git provider](https://orochibraru.com/homerun/canary/docs/git-providers.md): 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… - [Deploy on push](https://orochibraru.com/homerun/canary/docs/deploy-on-push.md): 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… - [Deploying from CI](https://orochibraru.com/homerun/canary/docs/ci-cd.md): 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… - [Pull request previews](https://orochibraru.com/homerun/canary/docs/pull-request-previews.md): 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… - [Environments](https://orochibraru.com/homerun/canary/docs/environments.md): Advanced mode: simple mode hides the Environments list on a service's Environments & Deployments tab. Everything here keeps working either way, and a hidden… - [Release channels](https://orochibraru.com/homerun/canary/docs/release-channels.md): 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… - [Main is canary, tags are stable](https://orochibraru.com/homerun/canary/docs/main-canary-tags-stable.md): 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… - [Test every pull request in its own environment with GitHub Actions](https://orochibraru.com/homerun/canary/docs/github-actions-preview-testing.md): 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… - [Required status checks](https://orochibraru.com/homerun/canary/docs/status-checks.md): 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… - [Importing a compose file](https://orochibraru.com/homerun/canary/docs/compose-import.md): 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… - [Migrating from Dokploy or Coolify](https://orochibraru.com/homerun/canary/docs/migrating-from-dokploy-or-coolify.md): Settings → Migrate (needs the Settings permission) reads another PaaS instance and recreates what it finds here. Pick Dokploy or Coolify, give it the instance… - [Deploying](https://orochibraru.com/homerun/canary/docs/deploying.md): 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… - [Revisions and rollback](https://orochibraru.com/homerun/canary/docs/revisions-and-rollback.md): 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… - [Image scanning](https://orochibraru.com/homerun/canary/docs/image-scanning.md): 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](https://orochibraru.com/homerun/canary/docs/env-vars.md): 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… - [Networking](https://orochibraru.com/homerun/canary/docs/networking.md): 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… - [Redirects](https://orochibraru.com/homerun/canary/docs/redirects.md): 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](https://orochibraru.com/homerun/canary/docs/error-pages.md): 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… - [DNS automation](https://orochibraru.com/homerun/canary/docs/dns-automation.md): 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](https://orochibraru.com/homerun/canary/docs/runtime-and-compute.md): 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… - [Swarm mode](https://orochibraru.com/homerun/canary/docs/swarm-mode.md): Instance-wide (/settings → Docker → Orchestration mode), and what the one-line installer sets up: the installer makes the system Docker daemon a swarm manager… - [Observability](https://orochibraru.com/homerun/canary/docs/observability.md): 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… - [Error tracking](https://orochibraru.com/homerun/canary/docs/error-tracking.md): 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… - [Tracing](https://orochibraru.com/homerun/canary/docs/tracing.md): 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… - [Pipelines](https://orochibraru.com/homerun/canary/docs/pipelines.md): Pipelines, under Observability in the sidebar, brings the CI runs of the repositories you choose into Homerun: GitHub Actions workflow runs, GitLab CI pipelines… - [Scheduling and the job queue](https://orochibraru.com/homerun/canary/docs/scheduling.md): 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](https://orochibraru.com/homerun/canary/docs/stacks.md): 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… - [Templates](https://orochibraru.com/homerun/canary/docs/templates.md): 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… - [Storage volumes](https://orochibraru.com/homerun/canary/docs/storage-volumes.md): 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… - [Volume backups](https://orochibraru.com/homerun/canary/docs/backups.md): 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… - [Object storage](https://orochibraru.com/homerun/canary/docs/object-storage.md): 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… - [Build servers & the Homerun Agent](https://orochibraru.com/homerun/canary/docs/remote-hosts-and-agent.md): 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… - [Workstations](https://orochibraru.com/homerun/canary/docs/workstations.md): 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… - [Machine terminals](https://orochibraru.com/homerun/canary/docs/machine-terminals.md): 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 roles](https://orochibraru.com/homerun/canary/docs/users-and-roles.md): 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… - [Authentication providers](https://orochibraru.com/homerun/canary/docs/authentication-providers.md): The Authentication page (Administration, needs the Users & authentication permission) is where sign-in methods are configured for the whole instance. It has… - [Your profile](https://orochibraru.com/homerun/canary/docs/your-profile.md): The profile pages (reached from the avatar menu, not the sidebar) are per account: - [Two-factor authentication and passkeys](https://orochibraru.com/homerun/canary/docs/two-factor-and-passkeys.md): Both live under Profile → Security. - [Per-app login wall](https://orochibraru.com/homerun/canary/docs/login-wall.md): 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… - [Blocked paths and IP bans](https://orochibraru.com/homerun/canary/docs/blocked-paths-and-ip-bans.md): 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… - [Sign in with Homerun](https://orochibraru.com/homerun/canary/docs/sign-in-with-homerun.md): 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… - [The dashboard](https://orochibraru.com/homerun/canary/docs/dashboard.md): Every list page (services, stacks, templates, cron jobs, storage, remote hosts, build cache registries, backup destinations, users) has the same toolbar: a… - [System Logs](https://orochibraru.com/homerun/canary/docs/system-logs.md): 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](https://orochibraru.com/homerun/canary/docs/docker-cleanup.md): 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](https://orochibraru.com/homerun/canary/docs/registry.md): 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](https://orochibraru.com/homerun/canary/docs/notifications.md): 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… - [Status pages](https://orochibraru.com/homerun/canary/docs/status-pages.md): 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… - [Upgrading Homerun](https://orochibraru.com/homerun/canary/docs/upgrading.md): 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… - [API & CLI](https://orochibraru.com/homerun/canary/docs/api-and-cli.md): 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… - [MCP server for AI agents](https://orochibraru.com/homerun/canary/docs/mcp.md): 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… - [Infrastructure as code](https://orochibraru.com/homerun/canary/docs/infrastructure-as-code.md): Homerun can be managed with Terraform, OpenTofu or Pulumi: stacks, services and every setting the dashboard has, plus the objects around them. The…