dockup.yaml Config as Code: Plan and Apply Safely

dockup.yaml turns service configuration into a reviewable repository artifact. Instead of relying on remembered dashboard state, a team can declare branch, port, build and start commands, health checks, ordinary environment values, and domains in one file.

Dockup separates inspection from mutation. dockup plan shows the difference between the manifest and the live service without changing anything. dockup up applies the declared changes. Deletion remains opt-in through --prune.

What can dockup.yaml declare?

A service manifest can contain the production settings that benefit from code review:

service:
  branch: main
  port: 3000
  dockerfile: Dockerfile
  build: npm run build
  start: npm start
  healthcheck:
    path: /health
    interval: 5
    timeout: 3
    retries: 5
  env:
    NODE_ENV: production
    API_URL: https://api.example.com
  domains:
    - api.example.com
    - { domain: admin.example.com, port: 4000 }

The file is placed at the repository root by default. A different path can be selected with --file.

Do not place secrets in the env mapping. The manifest is committed, reviewed, cached, and copied like other source files. Use dockup env set --secret or an approved secret injection process for credentials.

CPU, RAM, and disk consumption remain usage-based and are measured per minute against the plan balance; the manifest should describe service configuration rather than billing assumptions.

How does dockup plan show configuration drift?

Run a read-only comparison before every apply:

dockup plan production/api --json

The result contains changes with aspects, fields, old values, new values, and actions. A plan may show that the branch changed, a health path differs, a domain will be added, or a plain environment value has drifted.

A plan is valuable in three situations:

Situation	What the plan reveals
Pull request changes manifest	Intended production effect before merge
Dashboard edited manually	Drift from the repository source
Agent proposes an update	Exact fields the agent intends to mutate
Incident recovery	Whether live state already differs from known config
Multi-environment setup	Differences between production and staging manifests

Planning does not lock the service. Live state can change between plan and apply, so high-risk workflows should keep the review and up close together and inspect the apply result.

A coding agent should return the plan JSON or a concise field-by-field summary. “Configuration looks good” is not a sufficient review artifact.

How does dockup up apply config as code?

Apply the default manifest:

dockup up production/api --json

Apply and then trigger a deployment:

dockup up production/api --deploy --json

Use a different file for staging:

dockup plan production/api \
  --file dockup.production.yaml \
  --json

dockup up production/api \
  --file dockup.production.yaml \
  --deploy \
  --json

The apply result reports which changes were applied or skipped and can include the deployment ID when --deploy is used. The surrounding deployment should still use terminal-state verification where appropriate; a configuration mutation and a healthy production release are separate outcomes.

Secret values remain outside the manifest. Set them through the secret environment workflow before applying configuration, then deploy and verify the resulting container without printing the stored value.

Why is config as code additive by default?

The safest interpretation of an incomplete manifest is “manage these declared values,” not “delete everything else.” Dockup therefore leaves environment variables and domains that are absent from the file unchanged.

This matters during gradual adoption. A service may already have secret variables, operational domains, or temporary configuration that has not yet been modeled. The first up should not erase them.

The safety guarantees are specific:

• dockup up does not delete services, databases, or volumes.
• Existing secret variables are not overwritten by plain manifest values.
• Secret variables are not pruned.
• Automatic manifest application during deploy is additive.
• An invalid manifest does not silently become a destructive cleanup.

Additive behavior makes dockup.yaml suitable for an incremental GitOps workflow. It also means the manifest is not automatically a complete inventory unless the team deliberately adopts pruning for supported fields.

How should --prune be reviewed?

--prune removes supported plain environment values and domains that are absent from the manifest:

dockup plan production/api --json
dockup up production/api --prune --json

Treat the flag as a destructive request. Review the plan, state the exact target, and obtain human approval when an agent is operating production.

The operation does not extend to secrets, services, databases, or volumes. Those resources have their own lifecycle and confirmation paths. That separation prevents a small manifest edit from turning into broad infrastructure deletion.

A useful approval record says: “Apply dockup.yaml to production/api and prune the two plain variables and one domain shown in plan X.” It should not be a reusable blanket permission for future plans.

The broader confirmation model is discussed in production guardrails for AI agents.

How do teams operate a GitOps workflow with dockup.yaml?

Keep the workflow simple:

1. A developer or agent edits dockup.yaml.
2. CI validates YAML syntax and application tests.
3. A read-only dockup plan runs against the intended target.
4. The pull request shows both source diff and live-state plan.
5. A reviewer approves the change.
6. dockup up --deploy applies it.
7. The deploy waits for terminal success.
8. Status, logs, and audit evidence are retained.

The manifest should not become a dumping ground. Keep application business configuration in the application when appropriate. Use dockup.yaml for deployment and runtime settings owned by the service boundary.

Environment-specific files may be clearer than one file with an undocumented templating layer. For example, use dockup.staging.yaml and dockup.production.yaml, and pass the intended file explicitly.

A branch preview is an isolated deployment, while production config remains a separate review target. In private-networking projects, previews can join the project network and receive read-only database access without changing the production manifest.

Use the environment variables and secrets guide for credential handling and zero-downtime deployments for the readiness gate.

Drift response playbook

When dockup plan reports unexpected live changes, do not automatically overwrite them. Determine whether the dashboard edit was an emergency fix, an unauthorized change, or an intended setting that was never committed.

Then choose one source of truth:

• Update the manifest to preserve the intended live value.
• Apply the manifest to restore the reviewed value.
• Document a temporary exception with an owner and expiry.
• Investigate the audit log when the origin is unknown.

dockup audit --writes --json

This process keeps dockup.yaml authoritative without erasing incident context.

The Dockup CLI reference is the source for current manifest fields and plan/up options.

Design reviewable manifest changes

Keep each change small enough that the plan has one clear purpose. Combining a branch change, resource increase, new domain, health-check rewrite, and environment cleanup in one pull request makes both review and rollback harder.

Use comments to explain unusual values, but do not duplicate operational documentation inside the file. Link the repository runbook to the service target, health semantics, and approval policy. The manifest should remain valid YAML that can be parsed without a custom preprocessor.

A useful pull-request template asks for the dockup plan --json output, the expected deployment effect, whether --prune is requested, and the previous deployment ID. This gives an AI agent or human reviewer the same evidence.

Introduce the manifest without disrupting live state

For an existing service, begin with the fields you can verify. Run dockup info production/api --json, write a minimal dockup.yaml, and compare it with dockup plan. Add settings in stages rather than trying to reconstruct every historical dashboard choice at once.

Because apply is additive, unmanaged plain values and domains remain while adoption proceeds. Once the manifest accurately represents intended non-secret configuration, decide whether the team will ever use pruning. Some teams keep cleanup manual; others allow --prune only in a protected pipeline after plan approval.

The goal of config as code is not to maximize the number of lines in Git. It is to make production intent understandable, reviewable, and recoverable.

Keep plans free of secret material

A plan should be safe to attach to a pull request or incident record. Since dockup.yaml contains only plain values and existing secret values remain protected, reviewers can inspect intended configuration without receiving production credentials. Still review ordinary values for internal hostnames, customer identifiers, or other data that should not be public.

Keep the source and target together

Name the intended project/service in the pull request and deployment job. A valid dockup.yaml applied to the wrong target is still an operational failure. Target discovery and manifest review are separate required checks.

Validate YAML before plan

Parse the manifest in CI before calling Dockup so indentation or type errors fail close to the source change. Syntax validation does not replace dockup plan; it prevents avoidable requests with an unreadable file.

Prefer one source

A reviewed dockup.yaml should explain production intent.

Start with a verifiable deployment

Add a minimal manifest to one service, run a read-only plan, and review every reported field before the first apply.

Start free at app.dockup.ai. The Free plan is $0 per month, includes $2.50 in starting credit, and supports one workspace, three databases, and three deployments.

FAQ

What is dockup.yaml?

It is Dockup's config-as-code manifest for declaring service branch, port, build and start settings, health checks, plain environment values, and domains.

Does dockup plan change production?

No. dockup plan is read-only and shows the difference between the manifest and the live service.

Does dockup up delete configuration not in the file?

Not by default. Apply is additive. Supported plain environment values and domains are removed only when --prune is explicitly used.

Can secrets be stored in dockup.yaml?

They should not be. Commit only plain values; set secrets through the secret environment command or runtime secret injection. Existing secrets are protected from pruning.

Can dockup up deploy after applying configuration?

Yes. The documented --deploy option applies the manifest and triggers a deployment, whose terminal result should then be verified.