Docs / .deploymill/project.json reference
Guidedeploymill://guides/project-config

.deploymill/project.json reference (deploymill)

This file lives at .deploymill/project.json in the app's repo. It is the source of truth for everything reconcile_project reconciles to live app state: production domain, named-volume mounts, compute resource limits (CPU/memory), rollback toggle, optional managed Postgres database, optional managed object storage.

Preview lifecycle is not in this file — previews are MCP-driven (create_preview / delete_preview), not declarative.

Schema (version 2)

{
  "version": 2,
  "name": "my-app",
  "workload": "web",
  "port": 8000,
  "resources": { "cpu": 1, "memoryMb": 1024 },
  "domains": {
    "prod": "my-app-acme.detz.dev",
    "custom": ["www.acme.com", "acme.com"]
  },
  "mounts": [
    { "volumeName": "my-app-data", "mountPath": "/data" }
  ],
  "rollback": false,
  "health": { "path": "/healthz", "retries": 3, "intervalMs": 3000, "timeoutMs": 5000 },
  "source": { "provider": "github" },
  "database": { "provider": "neon" },
  "storage": { "provider": "r2" },
  "protection": { "enabled": false, "username": "user" },
  "previews": { "enabled": true, "shareDatabase": false, "shareVolumes": false, "shareStorage": false },
  "secrets": ["ANTHROPIC_API_KEY", { "name": "SENDGRID_KEY", "as": "EMAIL_KEY" }]
}

A worker (no HTTP edge) sets "workload": "worker" and omits port and the whole domains block — there's no domain to reconcile and no edge to probe. Everything else (mounts, rollback, database, secrets) works the same:

{
  "version": 2,
  "name": "my-worker",
  "workload": "worker",
  "mounts": [],
  "rollback": false,
  "database": { "provider": "neon" }
}

Fields

  • version (2) — required. v1 files are rejected with a clear migration message.
  • name (string, 1–80) — the user-facing app name. start_project keeps this aligned with the deployed app name; don't rename without re-running reconcile.
  • workload ("web" | "worker", default "web") — what kind of app this is. "web" is an HTTP server on a port behind a domain and must declare domains.prod — reconcile_project / import_repo error if workload is "web" (or defaulted) and domains.prod is missing, so a typo can't silently mis-provision. "worker" is a long-running background process with no HTTP server (a queue consumer, a scheduler, etc.): omit port and the whole domains block, and reconcile attaches no domain, skips the edge health-probe, and deploy returns url: null. Files written before this field existed default to "web". (Scaffold a worker with start_project({ stack: "node" | "python", workload: "worker" }).)
  • port (number, 1–65535, optional) — the port the container listens on inside its image. This is a compute concern, kept flat rather than nested under domains because one container serves a single port that any number of domains route to. When set, reconcile_project syncs both the app's container port and the prod domain's target port to this value (recreating the domain row if its port drifted). When omitted, deploymill falls back to whatever port the app row already has (older configs predate this field). import_repo reads it ahead of the stack default. If your prod URL returns a 502, the usual cause is this not matching the Dockerfile's EXPOSE / listening port — set it and reconcile.
  • resources (object, optional) — compute resource limits (the size of the container the app runs in). Provider-neutral units: cpu is a count of CPU cores (fractions allowed — 0.5, 1, 2; range 0.001–64) and memoryMb is a hard memory cap in megabytes (integer, 16–524288). Both are optional. Declarative & non-destructive like protection: omitting the whole block leaves whatever limits the app already has untouched (apps created before this field keep the platform default — unbounded). When the block is present it's the full source of truth for limits, so an absent field inside it means "no limit" on that dimension ("resources": {} clears both). reconcile_project reports the diff in plan.resources (current / desired in neutral units, plus an action of none / update / clear) and applies it through the compute primitive — no Docker/Dokploy concept appears in the config, so a future non-Dokploy compute backend maps the same shape onto its own machine size. Limits take effect on the next deploy (the orchestrator re-creates the container), which reconcile flags in its note. Works for both web apps and workers. Use it to give a memory-hungry app more headroom (e.g. after an OOM kill) or to cap a noisy one. Applying limits is best-effort — if the backend rejects them the rest of the reconcile still succeeds and the failure is surfaced as a warning.
  • domains (object, optional) — required for a web app (see workload). A web app declares domains.prod; a worker omits the whole domains block (and port). Reconcile errors if workload is "web" and this block is missing, rather than silently reclassifying the app. A worker still holds an active-app quota slot while it runs.
  • domains.prod (string, required for web apps) — the production hostname. Reconcile ensures the app has a domain row with this host pointing at port. A different host already attached is reported as drift (removed only with prune: true); a port mismatch on the prod host is auto-corrected (the row is recreated on the configured port).
  • domains.custom (array of hostnames, optional) — additional domains you own (e.g. ["www.acme.com", "acme.com"]), on top of the auto-derived prod host. Reconcile attaches each with HTTPS (Let's Encrypt), and validates every entry before attaching: hostname syntax, that it isn't under the platform wildcard domain (that namespace is deploymill's), that you've proven ownership of it (a one-time DNS TXT record — the first attempt is blocked with domain_verification_required carrying the exact record to publish, then remembered for your org), and that its DNS points at deploymill's ingress — a CNAME to the platform domain, or (for an apex like acme.com) an A record matching the platform domain's IP. An entry that fails validation is skipped with a warning (surfaced in plan.domains.blocked with a machine-readable code such as dns_not_pointed, carrying the exact record to create) — the rest of the reconcile still applies, so fix DNS and re-run. With prune: true, a custom domain removed from this list is detached. Point DNS first, then add the host here and reconcile, or the cert won't issue. deploymill issues the TLS cert for you — Let's Encrypt, via an HTTP-01 challenge served from deploymill's origin; you do not bring your own cert. Because that challenge has to reach the origin, the record must be DNS-only / unproxied: CNAME it straight at the deploymill ingress host the error reports (or A-record it at that host's IP for an apex), not behind your own Cloudflare/CDN proxy — an orange-clouded record intercepts the challenge and no cert issues. Each custom domain gets its own per-host cert under your domain's Let's Encrypt budget, so this scales across tenants. (For a one-off attach outside the file, use attach_domain with an explicit host; to remove one, detach_domain — but a host still listed here will be re-added on the next reconcile.) Full custom-domain playbook (both DNS steps, the coded errors, apex vs subdomain, the unproxied requirement): deploymill://guides/domains.
  • mounts (array, default []) — named volumes for per-app persistent storage: anything an app writes to disk that must survive a redeploy (user uploads/media, an on-disk cache, a local search/vector index, an embedded datastore). Managed Postgres should go through database instead — volumes are for filesystem state, not your primary DB. Each entry is { volumeName, mountPath }:
    • volumeName — volume name ([a-zA-Z0-9][a-zA-Z0-9_.-]*, max 60 chars).
    • mountPath — absolute path inside the container (/data, /var/lib/uploads, etc.).
    • Size: there's no size knob — every volume is the standard 20 GB (nominal, not yet kernel-enforced per-volume). Your org has a soft total-storage quota (default 100 GB, i.e. 5 volumes across all apps and previews). reconcile_project reports this in plan.storage when a mount add is on the table and refuses the apply with storage_limit_reached ({ limitGb, currentGb, requestedGb }) if the add would push you over. Free quota by removing mounts (reconcile with prune: true) or deleting old previews. For large/long-lived blobs (media, datasets) use object storage instead, not a volume. See deploymill://guides/storage.
    • Scope: a volume is attached to one app. There is no cross-app or cross-org shared volume — share state through a service (the database) instead. Previews get their own fresh volume per declared mount (see deploymill://guides/previews).
    • Full playbook (when to use a volume vs the database, write-under-mountPath rule, removing/renaming): deploymill://guides/storage.
  • rollback (true | false | "auto") — opt into fast image-swap rollback. Requires the server to be configured with container-registry credentials. Once on, every deploy pushes its image to the registry so it can be restored without a rebuild. "auto" additionally arms self-healing: if a deploy goes live but the health gate (see health below) comes back unhealthy, deploy automatically reverts to the last recorded-healthy image and reports it (in its autoRollback field) — you don't have to watch for it. See deploymill://guides/rollback.
  • health (optional object) — the app's health-endpoint contract, the canonical "is this deploy good?" signal that deploy/rollback/get_app_health and auto-rollback all key off. { "path": "/healthz", "retries": 3, "intervalMs": 3000, "timeoutMs": 5000 } — path is probed strictly (only 200 is healthy; any other status, a connection error, or a timeout is unhealthy), declared unhealthy only after retries consecutive failures spaced by intervalMs (each attempt bounded by timeoutMs). Set path: "/" to opt out into the lenient gateway-only root probe. Declaring this block also wires the endpoint into the container's Swarm HEALTHCHECK (start-first / failure-action=rollback), so the orchestrator won't cut over to an unhealthy new task. Omitting the block keeps existing apps working (the probe still defaults to /healthz with a lenient / fallback on a 404, but no Swarm HEALTHCHECK is wired). Workers have no HTTP edge → no health gate. Full contract: deploymill://guides/health.
  • source (optional { "provider", "owner"?, "repo"?, "url"? }) — where this project's source lives. Provider-neutral, mirroring database: provider is one of "github" | "gitea" | "external" (today only GitHub is wired). owner/repo/url are optional hints — for GitHub the repo location is implied by where the file lives, so start_project writes just { "provider": "github" }. Omit the block entirely to fall back to the server's default SOURCE_PROVIDER (GitHub). Read by import_repo; not otherwise reconciled.
  • database (optional { "provider": "neon" }) — provision a managed Postgres database. One database + role per app, pooled DATABASE_URL injected into the app's env. Requires the database provider to be configured on the server. After provisioning, fetch deploymill://guides/database/<stack> and follow it before the next deploy.
  • storage (optional { "provider": "r2" }) — provision a managed, S3-compatible object-storage bucket for blobs (user uploads/media, datasets, anything you serve to clients). One bucket + bucket-scoped credentials per app; S3_ENDPOINT/S3_REGION/S3_BUCKET/S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY are injected into the app's env. Requires the object-storage backend to be configured on the server. After provisioning, fetch deploymill://guides/storage/<stack> and follow it before the next deploy. Use this for blobs — not a volume (single-host, fixed-size) and not Postgres (structured data).
  • protection (optional { "enabled", "username"? }) — gate all HTTP traffic to the app behind HTTP Basic Auth. enabled (boolean) turns it on/off; username (default "user") is the Basic-Auth user. The password is never stored in this file — it's returned once at creation time by set_app_protection or reconcile_project and must be saved by the caller. Omitting the block leaves any existing protection untouched (reconcile is non-destructive by default); set enabled: false to explicitly remove protection. The tool interface is set_app_protection; add this block to persist the setting across reconciles. Provider-neutral (today's backend is the Dokploy/Traefik basicAuth middleware).
  • previews (optional) — preview-deployment config. Reconcile does NOT act on it — these fields are read by create_preview.
    • enabled (boolean) — informational. Tells agents whether this app expects previews.
    • shareDatabase (boolean, optional, default false) — when the app has a Neon database, previews fork their own Neon branch by default so destructive migrations stay off prod data. Set true to opt back into sharing the parent's DATABASE_URL. See deploymill://guides/previews for the full behavior matrix.
    • shareVolumes (boolean, optional, default false) — when the app declares mounts, each preview gets its own fresh volume per mountPath by default (preview writes never touch prod data). Set true to attach the parent's actual volumes to previews instead (concurrent-writer corruption risk — read-mostly volumes only). See deploymill://guides/previews.
    • shareStorage (boolean, optional, default false) — when the app declares storage, each preview gets its own fresh, empty bucket by default (preview writes never touch prod blobs). Set true to point the preview's S3_* at the parent's actual bucket instead. See deploymill://guides/previews.
  • secrets (optional array) — bind org-vault secrets into the app's env. Each entry is either a bare string (the vault secret name, used verbatim as the env key) or { "name", "as" } to map a vault name onto a different env key. On every reconcile the current vault value is resolved and written into the app's env (rotating the vault re-syncs here). Only names live in the file — values never do. Requires the server to have the secrets store configured; declared-but-missing secrets are reported in plan.secrets.missing with a warning (reconcile doesn't fail). Removing an entry does NOT prune the env var — use delete_env_vars. Enter the secret value first via request_secret (browser hand-off — the value never passes through the agent). See deploymill://guides/secrets.

The workflow

  1. Edit the file in the repo — locally or via push_files. The file is the source of truth.
  2. Run reconcile_project with the app's applicationId and either repoUrl (read from GitHub) or config (pass the parsed object directly).
  3. Read the plan — additions are things reconcile will create, drift is live app state not declared in the file, conflicts are mismatches that need a human.
  4. Apply — by default reconcile applies non-destructive changes immediately. Pass dryRun: true to skip applying. Pass prune: true to also remove drift (destructive — opt-in).
  5. Redeploy if needed — mount and database changes require a redeploy. Reconcile's response includes a note field that calls this out.

Common operations

  • Adding a mount: add an entry to mounts, commit, reconcile, then deploy.
  • Removing a mount: drop the entry from mounts, commit, then run reconcile with prune: true. The volume is detached from the app; the underlying volume may or may not be deleted depending on the platform's retention setting.
  • Changing the prod domain: change domains.prod, commit, reconcile. The old domain is reported as drift; pass prune: true to remove it.
  • Adding a custom domain: two DNS records from the domain owner. (1) The first time your org attaches a host, reconcile blocks it with domain_verification_required (in plan.domains.blocked) carrying a TXT record to publish — proof you own it. (2) Point the domain's DNS at deploymill's ingress (a CNAME to the platform domain, or an A record matching its IP for an apex, DNS-only / unproxied). Add the hostname to domains.custom, commit, reconcile. Reconcile validates ownership + DNS and attaches it with a Let's Encrypt cert; anything not yet satisfied is reported in plan.domains.blocked (domain_verification_required / dns_not_pointed, each carrying the exact record) and skipped — fix it and reconcile again. Remove it from the list + prune: true to detach. Full playbook: deploymill://guides/domains.
  • Sizing the app (CPU/memory): add or edit resources (e.g. { "cpu": 2, "memoryMb": 2048 }), commit, reconcile, then deploy — limits take effect on the next deploy. To remove a limit, drop the field (or set "resources": {} to clear both). Common after an OOM kill: bump memoryMb.
  • Changing the container port: set/change port, commit, reconcile. Reconcile updates the app's container port and recreates the prod domain row on the new port (no prune needed — a wrong port is broken, not optional). Then deploy so the container rebuilds on the new port if its image changed too.
  • Enabling rollback: set rollback: true, commit, reconcile. The next deploy pushes the first rollback target. See the rollback guide.
  • Provisioning a database: add database: { provider: "neon" }, commit, reconcile. Reconcile returns a nextSteps.guideUri pointing at the per-stack database playbook — fetch and follow it before the next deploy.
  • Removing a database: drop the database field. Without prune: true reconcile warns about drift but leaves DATABASE_URL alone. With prune: true it removes the env var AND drops the managed database + role.
  • Provisioning object storage: add storage: { provider: "r2" }, commit, reconcile. Reconcile returns a nextSteps.guideUri pointing at the per-stack object-storage playbook — fetch and follow it before the next deploy.
  • Removing object storage: drop the storage field. Without prune: true reconcile warns about drift but leaves the S3_* env vars alone. With prune: true it removes the env vars AND drops the managed bucket + scoped credentials.
  • Binding a secret: enter its value once via request_secret (browser hand-off), add its name to the secrets array, commit, reconcile, then deploy. See deploymill://guides/secrets.
  • Provisioning a preview: out of scope for this file. Call create_preview({ parentApplicationId, ref }). See deploymill://guides/previews.

What reconcile does NOT do

  • Doesn't manage arbitrary env vars (except DATABASE_URL during database provisioning, the S3_* vars during object-storage provisioning, and any keys bound via the secrets array). Use set_env_vars / delete_env_vars for everything else.
  • Doesn't push code. Use push_files to commit code (pass deploy: { applicationId }, or call deploy, to ship it — a commit no longer auto-deploys).
  • Doesn't run migrations. Migrations happen at container start (see database guides).
  • Doesn't manage previews. Use create_preview / delete_preview.

What NOT to do

  • Don't edit reconciled state out-of-band. The platform doesn't know about .deploymill/project.json; the file in the repo is the only source of truth, and changes made elsewhere will surface as drift.
  • Don't add fields the schema doesn't define. The schema is strict() — unknown fields fail validation.
  • Don't depend on prune: true being safe. It deletes drift unconditionally. Always run dryRun: true first if you're not sure what drift exists.

Troubleshooting

  • failed schema validation → the file has a typo or missing required field. The error message points at the offending field path.
  • version 1 is no longer supported → bump version to 2 and remove domains.previews (previews are now MCP-driven).
  • Unsupported version → the file has version not equal to 2. Either fix it or upgrade deploymill.
  • Drift you can't explain → someone changed app state out-of-band. Either update the file to match (prune: false) or let reconcile remove it (prune: true).