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. Synq 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. Repo updates preserve your explicit edits and apply other changes automatically — see how Compose changes merge.

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, Synq 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 Synq deploys.

Synq 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: Synq neither reads it nor rewrites it.

Compose file in a subfolder

Synq looks for the compose file at the project root. If yours lives somewhere else — say deploy/docker-compose/docker-compose.yml — open Compose file in the deploy wizard and enter the path, then hit Scan. Synq re-reads the repo and picks up the services it declares. You can give either the file or the folder that holds it, and the filename doesn't have to be the standard one (stack.yml works).

Relative build: contexts are resolved the way compose resolves them — against the compose file's own folder — so a file in deploy/docker-compose/ can use build: ../../api to build the api directory at the repo root.

What build: means

build: is the docker build context: the directory docker builds from. COPY and ADD paths in that service's Dockerfile are relative to it, dockerfile: is looked up inside it, and the .dockerignore that applies is the one in that directory — exactly as docker compose build behaves. Use build: . when the service really does build from the repo root.

Two consequences worth knowing:

• A service whose build: directory has no Dockerfile fails with a clear error. It does not fall back to a Dockerfile elsewhere in the repo — that would build a different image under this service's name.
• Compose build.args and build.target are not modelled. Build arguments come from the service's environment variables instead (each is passed as a --build-arg).

BuildKit

Modern Dockerfile syntax — RUN --mount=type=cache, # syntax= directives, heredocs — needs BuildKit. Synq uses it automatically for a Dockerfile that requires it when it builds against a Docker socket, and on a remote server whenever that host's Docker CLI has the buildx plugin. If a build fails with the --mount option requires BuildKit, install the plugin on the build host (the docker-buildx-plugin package, or Docker's official packages) and redeploy. The build log names which builder it used.

To keep it in the repo instead of setting it per project, declare it in synq.json:

{ "composePath": "deploy/docker-compose/docker-compose.yml" }

The wizard field wins if you later change it there — the config file seeds the value, your edit is what deploys.

Database access during a Next.js build

If next build reports getaddrinfo ENOTFOUND db, followed by an error such as Failed to collect page data for /api/hours, code evaluated during the build tried to resolve the db hostname. Check the named route and its imported helpers for database initialization.

Use "dependsOn": ["db"] in synq.json (or depends_on: [db] in Compose). This orders container startup; it does not start Postgres before image builds or attach the builder to the services' network. Even an already-running database is not automatically reachable by its service name from the builder.

For a route that needs data only when handling a request, move Payload initialization into the existing GET or POST handler, or a helper called by that handler. Next.js can import route modules during the build, so export const dynamic = 'force-dynamic' alone does not prevent module-level await getPayload(...) or an eagerly created initialization promise from running. Check imported helpers and configuration for the same side effects.

For example, this Next.js 15 / Payload 3 handler initializes Payload when a request arrives. It assumes an hours collection; when adapting your own route, keep its existing authentication, query options, access checks, and response shape:

import config from "@payload-config";
import { getPayload } from "payload";

export const dynamic = "force-dynamic";

export async function GET() {
  const payload = await getPayload({ config });
  const result = await payload.find({
    collection: "hours",
    overrideAccess: false,
  });
  return Response.json(result);
}

overrideAccess: false applies the collection's access rules; retain any existing authenticated user context in your own queries. Keep the runtime connection string pointing at db:5432 when both running services share the project network.

If a page intentionally queries data during static generation, deferring an API handler will not remove that requirement. Supply a data source reachable from the build environment, or change that page to load its data at request time if that matches the application.

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 Synq re-reads the current Compose source (the repository for GitHub projects or localPath for local projects) and reconciles it against your service rows automatically. GitHub pushes use the same path and skip the scan only when the changed-file list proves the Compose file was untouched. 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.
synq 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), 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).

synq service start   --project my-app db
synq service stop    --project my-app db
synq service restart --project my-app db

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

When the repo and your edits disagree: drift

On each deploy Synq merges the current Compose source with your saved service configuration, comparing each field against the previously imported version:

• 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.

Routine Compose changes do not require Accept upstream or Keep mine before redeploying. Saved project and service environment values remain in place. A key omitted from the repo is retained as a local override, and an unresolved expression cannot replace the only saved value for that key. Remove a saved variable explicitly from the environment editor when you no longer need it.

If an older version left a pending review, the next deploy reconciles it automatically. The legacy resolution actions remain available: Accept upstream applies source configuration while preserving saved environment values; Keep mine retains the current configuration.

# Accept a legacy source review; saved environment values are preserved
synq service drift accept --project my-app web

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

Ports & volumes

On Synq a stack runs on Docker, on the Synq server or on one of your own servers, with full compose semantics: host:container port mappings are published on the host, and volumes (named or bind mounts) are mounted.

Compose port publishing and Synq-managed domain routing are separate ownership boundaries. A domain is changed only when you explicitly configure a project/service endpoint in Synq; an unrelated Caddy, nginx, or Traefik vhost is never inferred from ports and is never rewritten. For an Synq-managed domain on the same server, redeploy keeps its tracked host port pinned so the route cannot silently move to a different upstream.

When a host port is already taken

A host port is one namespace per server, shared by every project on it. What happens when the port you want is already used by another app depends on who chose it:

• A port you typed in a service's Ports editor is never changed. Saving is refused with the name of the app or process that holds it, and the row offers Auto-assign.
• Leave the published port empty in the Ports editor and Synq picks it: the target port when it is free, otherwise the next free port above it.
• Expose to the internet on a database uses the engine's standard port (5432, 3306, ...) unless you type another; when the standard port is taken it uses the next free one.
• One-click app templates choose their own host ports. Installing two apps that want the same port on one server never fails: the second install, and a first deploy that finds the port in use, moves to the next free port.

Synq skips the ports it reserves, other projects' ports and routing claims, ports already chosen in the same request, and anything listening on the server. It looks at most 100 ports above the wanted one and never lands in the privileged range below 1024 (a taken 80 continues at 8080). The new port is saved on the service, and Synq says so in the deploy log and in the dashboard, for example: Port 8401 was in use by project "Grocy"; this app now uses 8402.

External networks, extra hosts and stop grace period

Every service joins the stack's project network, where it answers to its service name. These settings describe how a container sits on its host. They live in the service's advanced block, are shown under Settings → Networking → Host networking, and are applied on the next deploy:

A host port pinned to one interface (127.0.0.1:6379:6379) is published on exactly that interface. External networks declared in a compose file are still flattened into the project network on import; set them on the service (a migrated service gets them from its running container).

CLI

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.

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

Troubleshooting

Related guides