guides

Build packs and Docker Compose

How ServOS builds a service: Docker Compose stacks, Dockerfiles, Nixpacks, or a ready-made image.

Build packs and Docker Compose

A service is built one of four ways. When you pick a GitHub repository and branch, ServOS looks inside it first and preselects the one that fits.

Build pack	What ServOS does	Picked when the repository has
Docker Compose	Runs every service in the compose file with `docker compose`	a `compose.yaml` / `docker-compose.yml`
Dockerfile	Builds one image and runs it with zero-downtime swaps	a `Dockerfile`
Nixpacks	Works out the language and builds without a Dockerfile	`package.json`, `go.mod`, `requirements.txt`, …
Image	Pulls and runs a published image	(not built from a repository)

For a monorepo, set Base directory to the folder the app lives in; the folders at the top of the repository are offered as one-tap choices.

Docker Compose stacks

ServOS runs the compose file as written. Builds, networks, volumes, healthchecks, depends_on, one-shot jobs and every other Compose feature are Compose’s own. ServOS adds only what a platform has to own, in a rendered copy (docker-compose.servos.yml) beside your file:

Domains. Give any compose service one or more domains and the port it listens on. ServOS adds the proxy labels and HTTPS certificates. Services without a domain stay private.
Environment. Variables you set on the service fill ${VARS} in the file. With Give every service the environment variables on (the default, and what Coolify does), every service also receives them. Values are passed through a file only the deploying user can read, never written into the compose file.
Networks. Every compose service joins the ServOS environment network as <service-name>-<compose-service>, so other services in the environment can reach it.
Missing env files. An env_file that exists only on a developer’s laptop (it is git-ignored) is dropped with a warning instead of failing the deploy.

The form lists every service in the file, with its ports, healthcheck and dependencies, and every ${VAR} it uses. Variables with no value and no default are flagged before the first deploy.

Deploying

ServOS fetches the exact commit into /var/lib/servos/stacks/<project>/src on the server. Files the stack writes there (relative bind mounts) are kept between deploys.
It validates the rendered file with docker compose config, pulls images, and builds the services that build.
It starts the stack and waits until every service is healthy (or running, when it has no healthcheck), and one-shot services such as migrations have exited cleanly. A service that is unhealthy, keeps restarting or exits with an error fails the deploy, with its last log lines in the deploy log.

The service page shows each compose service’s state, with start, stop, restart and logs for one service or the whole stack.

You can also paste a compose file instead of using a repository.

Deploying on push

Pushes to the tracked branch deploy the service. When the GitHub App’s webhook points at ServOS, deploys start the moment GitHub delivers the push. Until then (for instance while ServOS has no public HTTPS address, or while the App’s webhook still goes to Coolify), ServOS checks the head of each tracked branch every minute and deploys new commits. Either way the exact pushed commit is built.

Pull request previews

Turn on Preview every pull request for a service built from a GitHub repository. Each pull request to the tracked branch gets its own copy with pr-<number>. in front of every domain. A preview stack gets its own Compose project and fresh volumes; it never mounts production data. Closing the pull request removes the copy.