Compose & multi-service apps

Some apps aren't one thing — they're a team. A website out front, a background worker doing slow jobs, and a database holding the data. Think of a restaurant: the dining room, the kitchen, and the pantry are three separate stations, but together they're one restaurant. Alaf Server calls a set of services that run together a stack, and it can run the whole stack for you.

Each service in the stack is its own little box (a container) with its own image, ports, storage, and settings — but you manage them all from one place: the project's Services tab.

Where your services live

Open your project and choose the Services tab. You'll see one row per service. Each row tells you, at a glance:

• The service name (e.g. web, worker, db).
• A Public or Internal badge — Public means it has a web address people can visit; Internal means only the other services can reach it (a database is almost always Internal).
• A status dot: Running, Stopped, Starting, Failed, or Disabled.

Click any row to open that service's full screen. If the repo changed a value you'd edited, the row also shows an Upstream change badge — more on that in Drift.

How services get into a stack

There are two ways, and you can mix them.

1. From a docker-compose.yml file

If your repo has a compose file, Alaf Server reads it and turns each service in the file into a service row — its image (or a build context and Dockerfile), ports, volumes, environment, command, restart policy, depends_on links, and healthcheck. From then on those rows are what Alaf Server deploys.

Alaf Server tracks the compose fields it models: image, build, dockerfile, ports, depends_on, environment, volumes, command, restart, and healthcheck. Everything else in your file — networks, build args, labels, profiles, comments — is left untouched: Alaf Server neither reads it nor rewrites it.

2. Added by hand

Any project can get extra services from a built-in catalog of common images — databases, caches, search, queues, storage, and more — or from any Docker image you name.

Re-syncing after the compose file changes

You don't normally sync by hand — on every deploy (and on every push, for GitHub-backed projects) Alaf Server re-reads the repo's current docker-compose.yml and reconciles it against your service rows automatically. From the terminal you can also force a sync from a specific file:

# Rebuild the stack's service rows from a compose file.
# Services in the stack but NOT in the file are removed — you'll be asked to confirm.
alaf server service sync --project my-app ./docker-compose.yml

Opening a service

Click a service row to open its screen. Across the top is a row of tabs:

• Overview — read-only facts, each shown only when it applies: Network (the internal address other services use to reach this one, the container ports, the published host port, the current IP, and the container ID — shown as a Workspace ID on Alaf Server Cloud), Configuration (restart policy, command, depends-on), and Volumes.
• Terminal — a live shell inside the container. It only opens while the service is Running ("Start the service to open a shell." until then).
• Logs — the service's output, streamed as it happens.
• Environment — the service's environment variables. Edit them and press Save environment.
• Settings — the build and runtime fields you can change: name, image (or a build context and Dockerfile), ports, depends-on, volumes, command, restart policy, and an optional healthcheck — plus the enable toggle, the lifecycle buttons, and Delete. (Environment variables have their own Environment tab.)
• Backup — schedule and run backups. This tab shows only for compose services (the stateful containers), not for source-built sub-apps.

Start, stop, restart

The lifecycle buttons live on the service's Settings tab. Which ones appear depends on the state:

• Running → Stop and Restart.
• Stopped → Start.
• Disabled (never started) → Enable & start, which turns the service on and deploys it.
• Enabled with a live deployment → Redeploy, which rebuilds only this service and leaves the rest of the stack running.

There's also Disable Service / Enable Service (a disabled service is skipped on deploy) and Delete (tears the service down).

alaf server service start   --project my-app db
alaf server service stop    --project my-app db
alaf server service restart --project my-app db

# See what's actually running
alaf server service containers --project my-app

When the repo and your edits disagree: drift

Here's the tricky bit, made simple. You can edit a service in the dashboard and keep a docker-compose.yml in your repo. What happens when both change the same value?

On each deploy Alaf Server does a three-way compare for every service:

• base — the compose values it last read in,
• yours — the service's current values (including your dashboard edits),
• theirs — what the repo file says right now.

So services you never touched track the repo on their own, and your edits are never overwritten without asking. When a value you'd edited changes in the repo, the Services tab shows an amber drift banner with a per-field from → to diff and two choices per service:

• Accept upstream — take the repo's value and move your baseline to it.
• Keep mine — keep your value; the flag clears so it stops nagging, but your edit stays in effect.

# Take the repo's values, discarding your edits
alaf server service drift accept --project my-app web

# Keep your edits and stop flagging the change
alaf server service drift keep --project my-app web

Ports & volumes: cloud vs self-hosted

How ports and volumes behave depends on where the stack runs:

• Self-hosted / your own server (Docker): full compose semantics. host:container port mappings are published on the host, and volumes (named or bind mounts) are mounted.
• Alaf Server Cloud: only the container port matters — it's routed to your domain through the edge proxy, and a published host port is ignored. Docker volume mounts don't apply. A cloud service's data lives on its workspace disk, which survives restarts but is not carried across a rebuild unless you turn on backups.

You'll see this in the interface too. When you set the stack up in the deploy wizard, a cloud project greys out the published (host) port and the volume fields and notes that only the container port is routed. Stateful images — databases like Postgres, MySQL, MariaDB, MongoDB, Redis or Elasticsearch, and any service that declares a volume — get an amber reminder that their data isn't kept across a rebuild unless you turn on backups. Later, on the Services tab, a cloud service's Overview shows a Workspace ID in place of the Container ID.

Prefer the terminal?

Every service action has a CLI command. All of them target a stack with -p / --project (id, slug, or name) and a service by name or svc_… id.

alaf server service list    --project my-app                 # list the services
alaf server service get     --project my-app db              # show one service's config
alaf server service create  --project my-app cache \
  --image redis:7 --port 6379                             # add a service by hand
alaf server service sync    --project my-app ./docker-compose.yml
alaf server service start   --project my-app web             # start / stop / restart
alaf server service logs    --project my-app web --follow    # stream logs
alaf server service env set --project my-app web KEY=value   # set env vars (--secret, -e <env>)
alaf server service drift accept --project my-app web        # resolve drift
alaf server service delete  --project my-app cache           # remove a service

If something goes wrong

What next?