Compose validation

How Kowan checks a Docker Compose file before it deploys: syntax, port and name conflicts on the host, missing secrets and risky settings, with one-click fixes.

Kowan checks a Compose file while you edit it and again before it is saved or deployed. It catches what would make docker compose up fail, or quietly misbehave, on the target host: a port already in use, a volume nobody declared, a secret that does not exist. Errors block the deploy; warnings and tips do not.

Where validation runs

In the editor

The Compose section of the deployment form validates the file shortly after you stop typing, in both the Easy and the YAML editor. Results appear in the Validation panel under the editor, and the YAML editor marks the lines.

When you save or deploy

Creating, editing, deploying, rolling back, promoting and importing an inline Compose deployment all go through the same check on the server. Any error refuses the change with the list of problems.

In GitOps

A Deployment resource with Compose content is checked when a GitOps sync computes its plan. An error fails the plan, and a plan with errors is never applied.

A Compose file read from a Git repository by a Git deployment is not checked by this gate.

Read and fix the results

Each finding has a severity, a message and, when known, a position.

To work through them:

1. Click a finding's position to jump to that line in the YAML editor. From the Easy editor, this switches to YAML.
2. When Kowan knows a safe fix, click Apply fix. It edits the file in place and keeps your comments and layout.
3. Fix the remaining errors by hand. No problems found means the file is clean.
4. If warnings remain, tick Deploy with N warnings to confirm you reviewed them. The confirmation covers exactly that set of warnings: a new one asks again.

What Kowan checks

Structure

Kowan runs docker compose config on the file, as Docker itself would read it, and maps the error messages back to a line. The Kowan server image includes the Compose plugin; when it is not available, Kowan falls back to a built-in check of the file's shape (top-level keys, service structure, list and map types, undeclared networks, duplicate keys). YAML syntax errors are reported with the parser's position.

Kowan secret references such as [[db.password]] never break the YAML check, and an env_file is read on the target host, so a missing one is reported as info, not as an error.

Rules

A variable counts as set when it is one of the deployment's stack variables. A variable with a default (${TAG:-1.27}) never warns. To fix a missing variable, add it under Stack variables or give it a default.

Host checks

The port, container name and bind path checks look at the target host. They exclude the deployment's own containers, so a redeploy never conflicts with itself.

• They run only when the host answers within 5 seconds (KOWAN_COMPOSE_HOST_TIMEOUT). An offline host skips them silently.
• Bind paths can be checked only when the deployment targets the server's own host and the Kowan server runs directly on it, not in a container. With the usual container install, this check is skipped.

Validate from the API

POST /api/v1/compose/validate runs the same checks without saving anything. It needs the operator role.

{
  "compose": "services:\n  web:\n    image: nginx\n",
  "hostId": "local",
  "deploymentId": "",
  "env": { "TAG": "1.27" }
}

hostId turns on the host checks, deploymentId excludes an existing deployment's containers, and env lists the variables you will set. A bad file still answers 200: the problems come back as diagnostics, each with its severity, message, line and column (1-based, 0 when unknown) and, when available, a fix. The file can be up to 512 KiB. See REST API.

Settings

See Configuration for how to set environment variables.