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.

#Detected from the image, Dockerfile or manifest

As soon as you type an image (or pick a repository to build), the wizard reads what it declares and shows it under the source fields: exposed ports, volumes, environment variables, healthcheck, user, working directory, entrypoint and command.

• An image: its config, read from the registry without pulling any layers, or from this machine when the registry can't be reached.
• A git repository: its Homerun Manifest (.homerun.json, .homerun.yaml or .homerun.yml, looked up next to the build context first, then at the root, the same way a deploy does) laid over its Dockerfile. The manifest wins for the port, protocol, environment, healthcheck, user, command and entrypoint it sets, and its build method, context and Dockerfile path decide which Dockerfile is read (none, for a build method other than a Dockerfile). Its other keys are listed as applied on deploy. A manifest that doesn't validate shows its problems, since every deploy would fail on them. The Dockerfile is its final stage, plus whatever it inherits from earlier stages, with ARG/ENV defaults expanded; a stage built from an external base image only reports what the Dockerfile adds. The repository is read the same way a deploy reads it, so a public one works without a connected git provider.
• A git repository without a Dockerfile: the first marker file in the build context (docker-bake.hcl, package.json, deno.json, go.mod, Cargo.toml, pyproject.toml, requirements.txt, Gemfile, composer.json, pom.xml, build.gradle, mix.exs, index.html) names the runtime and the framework when a dependency gives it away (Next.js, Astro, Django, chi…), and switches the build method to Docker Bake or Railpack so the first deploy doesn't fail looking for a Dockerfile. A framework with a well-known default port (Next.js 3000, Astro 4321, Django 8000…) fills in the port when nothing else declared one.

What it fills in for you:

Every field filled in this way is marked detected. Change it and it's yours: a later detection (another tag, another branch) never overwrites it.

• Name: the manifest's name, the image's org.opencontainers.image.title label, or the project's name from package.json / go.mod, unless you already typed one.

• Build settings: the manifest's gitBuildMethod, gitBuildContext, gitDockerfilePath, gitBuildTarget and gitBakeFile, or the suggested build method.

• Routing: the manifest's primaryDomain (else its first domains entry), dnsResolvable and authRequired.

• Runtime: the manifest's restartPolicy, pullPolicy, cpuLimit, memoryLimitMb and replicas.

• Container port: the manifest's containerPort, else the first exposed TCP port (UDP when that's all there is), else a numeric PORT environment variable, else the framework's default port, unless you, a template or a previous submit already set one.

• Volumes: one new named volume per declared VOLUME path not already in the list. Change the source or the path and it stays yours; switch to another image and the untouched ones are swapped out.

• Environment variables: an Import from link in the Environment step adds the declared variables as editable rows, skipping the base-image plumbing (PATH, HOME, LANG, *_VERSION, and so on). It's a button, not automatic, because an imported value becomes an override that no longer follows the image when it changes.

Healthcheck, user, working directory, entrypoint and command are shown for reference only: the container already gets them from the image, and a manifest's are applied on every deploy, so there's nothing to copy. Override them on the service's tabs after it's created.

#The services list

Services has a search box (matches name, image, and domain) plus Status/ Stack filters, a sort (newest, oldest, name either way, recently updated; it's in the URL, so a sorted view can be bookmarked), and a list/card view toggle that remembers your choice on your account; both the search and filters are applied on the server, so they reach every service on the instance, not just whichever page happens to be on screen. Once you have more than a page's worth, a pager at the bottom shows "26–50 of 60" and lets you step through the rest. Check one or more services (a "select all" scopes to whatever's on the current page, paginating or changing the search/filters clears your selection) to bring up a bottom bar with bulk Start/Stop/Restart/Delete: bulk actions run against every selected service and report back which ones succeeded, so one service with no container yet doesn't block the rest. Bulk delete, and the single-row delete on this page and the delete under a service's own Settings → Danger zone, all require typing a confirmation phrase (the service's name for a single delete, delete N services for a bulk one) before the button unlocks, an irreversible action gets a real "are you sure" rather than a single click. A delete removes the container or swarm service first: one that's already gone is fine, but if Docker fails to remove it, the service is kept and the error says why. The Danger zone's delete then offers Delete anyway, which removes only Homerun's record (the REST API's equivalent is DELETE /api/v1/services/:id?force=true). A service with a deploy (or any other job) still queued or running, for itself or one of its previews, environments or canary, isn't deleted either: the Danger zone's delete dialog lists those jobs and its button becomes Force delete, which cancels them first. Deleting a preview or an environment on its own cancels its jobs without asking.

The Services page has three views, switched with List, Dependencies and Diagram next to the toolbar:

• Dependencies, the default, shows every service with what it needs indented underneath (the same tree a stack page shows, across the whole instance), and each service's lane: its last 24 hours of traffic in half-hour blocks with a diamond per deployment, tinted by its stack. Its search box narrows the tree to the services whose name, slug, image or main domain matches, keeping the services that need them above them.
• List is the paged list, grouped by stack and ordered as a tree (a substack's group indented under its parent's, services outside any stack last), with the sort, the status and stack filters and a search that runs on the server. A link with a search or a filter in it lands here.
• Diagram draws every stack as a frame with its services as cards, arrows from each service to what it needs, and the services in no stack in a frame of their own, with the same search box as Dependencies. Drag cards and frames around, zoom, or Fit it to the screen; the layout is kept in your browser.

#Settings

Three sections:

• General: name, slug, pull policy, restart policy, environment name, type and icon, which stack the service belongs to, and Save as template.
• Automation: auto-rollback, whether its image is scanned and the scheduled redeploy.
• Danger zone: the typed-confirm delete (see The services list).

Pull policy decides whether a deploy pulls the image: Always (the default, and the only way a moving tag like :latest picks up a new build), If missing (only when the image isn't on the host yet, faster redeploys but a moving tag goes stale), or Never (for an image built or loaded onto the host by hand, the deploy fails if it isn't there).

Save as template (under General) snapshots this service's current image, tag, port, env vars, resource limits, healthcheck and runtime options into a reusable template of your own, which then behaves exactly like a built-in one, including being linkable as a companion to another template. See Templates.

#Health

Observability → Health shows the healthcheck the running container was actually created with: whether it's the service's own command, the image's HEALTHCHECK, Homerun's generated port check or none, the command itself, its interval, timeout, retries and start period, its live status and the last few probes' exit codes and output. A swarm service's tasks aren't shown there.

Below it, the service's own settings, each taking effect on the next deploy:

• Command overrides the image's own Docker healthcheck with a shell command run inside the container (exit 0 = healthy). When a service has one, its uptime probe reports the healthcheck instead of knocking on the container port, which is what a portless container needs. It is also the service's readiness check: a new container or swarm task gets no traffic until it passes.
• Interval, Timeout, Retries and Start period override the defaults (30s, 10s, 3 and 30s). Interval, timeout and retries also apply to Homerun's generated port check.
• Turn off healthchecks removes every check: the image's own is overridden with none, Homerun adds no port check, and the post-deploy health watch doesn't wait for an HTTP answer. For a background worker that doesn't listen on anything.

#Everything else a service does

Each part of a service has its own page:

• Deploy source and build methods
• Deploy on push, pull request previews and required status checks
• Deploying and revisions and rollback
• Image scanning
• Env vars and storage volumes
• Networking, DNS automation and the per-app login wall
• Runtime and compute and swarm mode
• Observability: monitoring, uptime, logs, errors and the terminal
• Scheduling and the job queue