> 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…
> Source: https://orochibraru.com/homerun/docs/faq-and-limitations · Site index: https://orochibraru.com/llms.txt

# FAQ & limitations

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.

## Is this production-ready?

It's actively developed and runs on real hardware, but it's a single-maintainer
project, and "production" here means your homelab or your own server. Keep
[backups](https://orochibraru.com/homerun/docs/storage-volumes), and take a Postgres dump before a major upgrade:
migrations only run forward.

## Can several people share the same services?

Yes. Every account sees and manages every service, stack, volume, backup and the
rest of the instance's resources, whoever created them. Sessions, API keys,
preferences, git connections, the bell feed and notification channels stay
personal. There are no teams and no per-stack permissions: the two roles, admin
and developer, only differ in which instance-wide pages they can open. An API
key has the full permissions of its account. Deleting an account hands what it
created over to another admin. See [Users and roles](https://orochibraru.com/homerun/docs/users-and-roles).

## Can it build an app without a Dockerfile?

Yes. Besides a `Dockerfile` or a Docker Bake file (both built with BuildKit), a
git-based service can be built with Nixpacks, Railpack, or Cloud Native
Buildpacks (Heroku or Paketo builders), picked as the build method on the Source
tab. A build clones a branch, a tag or a specific commit, and pull requests can
get their own preview deployment. See
[Build methods](https://orochibraru.com/homerun/docs/deploy-source-and-builds#build-methods).

## Can it deploy to more than one server?

Not the way you might expect. Services run on the machine Homerun is installed
on. To spread a service across machines you turn on [swarm mode](https://orochibraru.com/homerun/docs/swarm-mode)
and join the other machines to the swarm as workers. There's no "add a server
and deploy to it" screen. [Build servers](https://orochibraru.com/homerun/docs/remote-hosts-and-agent) only
compile images, they never run services.

## Does it manage databases?

Not as a separate kind of resource. PostgreSQL, MySQL, Redis, MongoDB and others
are [templates](https://orochibraru.com/homerun/docs/templates) deployed like any other service, and
[service links](https://orochibraru.com/homerun/docs/env-vars) fill in the connection URL for the apps that use
them. Backups tar the database's volume while it runs, they don't run a dump
tool, so read the backup warning below.

## Can I bring my existing services over?

Mostly. **Settings → Migrate** reads another instance's applications, compose
stacks and databases with an API token and recreates them here without touching
the original. Apps built with Nixpacks, Railpack or buildpacks come across with
the same builder, along with their start commands, Dokploy's private registry
credentials and file mounts; static build packs can't. Persistent storage isn't
always listed by the other side's API, so check volumes after importing. A
pasted compose file works too, including `command`, `entrypoint`, `env_file`,
labels, `cap_add`, devices and `privileged`; `healthcheck`, secrets and configs
are dropped with a warning. See [Importing a compose file](https://orochibraru.com/homerun/docs/compose-import).

## Known, real limitations (not hypothetical)

- **The default install runs Docker as root.** Swarm mode, the default, needs
  the system Docker daemon because rootless Docker can't create overlay
  networks, and anything that can reach that daemon's socket is root on the
  host. `--docker=rootless` keeps Docker under an unprivileged user at the cost
  of swarm (standalone mode only). A rootless install moves over with
  `--migrate-to-rootful`, see
  [Getting started](https://orochibraru.com/homerun/docs/getting-started#moving-a-rootless-install-to-rootful--swarm).
- **Swarm mode only sees this host's replicas.** Per-replica usage, the Terminal
  tab and pre-backup commands only reach replicas running on this machine, and
  the uptime "from the network" probe doesn't run for swarm services.
- **Swarm mode ignores privileged mode and devices** and doesn't give a stack
  its own network. With several nodes, volumes are per node and locally built
  images need a build cache registry. See [Swarm mode](https://orochibraru.com/homerun/docs/swarm-mode).
- **Cloudflare and Pangolin DNS automation haven't been tried against real
  accounts.** Every deploy writes what each provider did into its log, so read
  the first one. Point Pangolin at its **Integration API** (its own port, base
  path `/v1`), not the dashboard's `/api/v1`. See
  [DNS automation](https://orochibraru.com/homerun/docs/dns-automation).
- **Deploy on push without a reachable dashboard polls every two minutes.** A
  GitHub repo can't deliver a webhook to a dashboard only reachable on your LAN,
  so Homerun reads the branch head through the provider's API instead, which
  only works for GitHub, GitLab, Gitea and Bitbucket. Pull request previews
  still need the webhook.
- **Every publicly routed app depends on the dashboard being up.** The login
  wall's check is attached to every service so it can be switched on and off
  without a redeploy, which means Traefik refuses requests to any routed app
  while Homerun itself is down. Removing someone at your identity provider is
  picked up within about five minutes when the app filters on groups and the
  provider issues refresh tokens, otherwise at their next sign-in or within
  eight hours. See [Per-app login wall](https://orochibraru.com/homerun/docs/login-wall).
- **Backups aren't paused for writes.** A volume is tarred while its service
  keeps running, which can tear a database mid-write. Dump the database into a
  bind mount with a [cron job](https://orochibraru.com/homerun/docs/scheduling#cron-jobs) and back that up
  instead. See [S3 backups](https://orochibraru.com/homerun/docs/backups#s3-compatible-backups).
- **Restoring a backup unpacks over the volume** without wiping it or stopping
  anything. Stop the services using it first. See
  [S3 backups](https://orochibraru.com/homerun/docs/backups#restoring-a-backup).
- **A rollback only restores the image.** Env vars, volumes and networking stay
  as they are now, and only the last 5 images of a service are kept on the host
  (configurable under Settings → Docker). Auto-rollback is off by default and
  replaces an unhealthy revision after it has taken traffic. See
  [Revisions and rollback](https://orochibraru.com/homerun/docs/revisions-and-rollback).
- **Pruning volumes in Docker Cleanup deletes data**, including volumes of
  services you've only stopped. Read the preview. See
  [Docker Cleanup](https://orochibraru.com/homerun/docs/docker-cleanup).
- **Image scanning lets a deploy through when it couldn't finish**, unless
  **Fail deploys when the image can't be scanned** is ticked under Settings →
  Docker. See [Image scanning](https://orochibraru.com/homerun/docs/image-scanning).
- **Health-gated redeploys need a healthcheck to really gate.** Without one the
  new container takes traffic as soon as it's been running a few seconds, and a
  service on host networking or with a writable volume still stops the old
  container first. See [Deploying](https://orochibraru.com/homerun/docs/deploying).
- **Changing your own verified email needs SMTP configured**, since the change
  is confirmed from the current address. Without SMTP, an admin can change it
  directly from `/users`. See [Your profile](https://orochibraru.com/homerun/docs/your-profile).
- **A direct-created account is a race without SMTP configured.** It has no
  password until it's chosen one at its first sign-in, and without SMTP there's
  no code step proving who's asking, so anyone who knows the new account's email
  can set its password before its real owner does. See
  [Users and roles](https://orochibraru.com/homerun/docs/users-and-roles).
- **Every registry token can both push and pull.** The built-in registry's
  htpasswd auth has no concept of scopes or read-only access without running a
  separate token server, so there's no pull-only credential to hand out. See
  [Registry](https://orochibraru.com/homerun/docs/registry#tokens).
- **Publishing the registry through a real Traefik hostname hasn't been pushed
  to yet.** Only the container's own htpasswd auth was verified directly
  (anonymous/wrong-password rejected, correct token accepted, a real
  `docker push` landed in the catalogue); a push over a published hostname with
  a real certificate is untested. See [Registry](https://orochibraru.com/homerun/docs/registry#whats-verified).

The live backlog is [`TODO.md`](https://github.com/orochibraru/homerun/blob/main/TODO.md).

## Where do I report a bug or ask something not covered here?

Open an issue against the repo. If you're contributing code, read
[`CLAUDE.md`](https://github.com/orochibraru/homerun/blob/main/CLAUDE.md) and the `.agents/notes/` it points to first.