Deploy Mill docs

Connect an MCP client to deploymill and go from nothing to a live app: authenticate, call start_project, push code, and find the URL. The first thing a new human or agent should read.

The main product is the MCP tools — this is how a human wires deploymill into their agent. One-time setup for Claude Code, Claude Desktop/claude.ai, Cursor, VS Code, and any other remote-MCP client: paste the endpoint URL, run the OAuth sign-in, done.

The one-page mental model: the neutral, agent-safe control plane over compute, database, domain, secrets, source, and object storage — driven entirely by MCP tools, neutral across provider backends, with the guardrails to hand an agent production. What it does, what it deliberately doesn't, and how the pieces fit.

The first place to look when something goes wrong: the deploy/build failure loop, common error codes and what they mean, the health-gate and DNS gotchas, and how to escalate when the docs run out.

How to run a deploymill org as a team from the /account/org dashboard: inviting teammates (single-use 7-day links), the owner/admin/member role capability matrix in plain language, changing roles and removing/leaving members, the last-owner rule, and seat limits (what happens at the cap).

Enterprise SSO for your org: how connections are operator-managed (OIDC/SAML, no self-serve, IdP secrets server-side only), domain-based auto-join (new users land as member), SSO enforcement (blocking password/Google for claimed domains), an Okta OIDC setup walkthrough (issuer, client id/secret, the /api/auth/sso/callback redirect URI, claimed domain), and the read-only /account/org/sso status page.

The maintained subprocessor / data-flow inventory for the default managed stack: which third parties (Dokploy, Neon, GitHub, Cloudflare R2, Linear, Resend, Google) receive what data categories, for what purpose, and the deployment-dependent caveats — for vendor-management, DPA, and GDPR Article 28 review.

The /api/v1 REST API: a read-only HTTP mirror of the MCP tool surface for scripts and CI pipelines. Covers the two endpoints (GET /api/v1/openapi.json and POST /api/v1/tools/:name), OAuth Bearer auth, the full list of available read tools, curl examples, and error codes.

Layout, PORT contract, Dockerfile conventions, common modifications, and what NOT to do when modifying a deploymill-managed Node app scaffolded from the `node` template.

Layout, host/port contract, Dockerfile conventions, common modifications, and what NOT to do when modifying a deploymill-managed Python app scaffolded from the `python` template.

Layout, Dockerfile conventions, what the static stack supports and doesn't (no env at runtime, no DB, no runtime mutation), and how to add assets or SPA routing.

deploymill's paved road for Node apps: the libraries the template and database guide already commit to (Hono, pnpm, pg + node-pg-migrate), recommended-but-optional picks for auth/validation/TypeScript, what deploymill has no opinion on, and the `.deploymill/conventions.md` project override. Read before writing non-trivial application code.

deploymill's paved road for Python apps: the libraries the template and database guide already commit to (FastAPI + uvicorn, uv, psycopg + alembic), recommended-but-optional picks for validation/auth/concurrency, what deploymill has no opinion on, and the `.deploymill/conventions.md` project override. Read before writing non-trivial application code.

Full schema for the project config file plus the edit-file-then-reconcile workflow: domain, mounts, rollback, database, dryRun/prune flags, and what reconcile does NOT do.

The end-to-end custom-domain playbook an agent follows to attach a domain the user owns: the one-time DNS TXT ownership proof (`domain_verification_required`), pointing the host at the ingress (CNAME for a subdomain / A record for an apex, DNS-only/unproxied), the coded errors each path returns (carrying the exact record to create), the automatic Let's Encrypt cert + propagation caveat, the `attach_domain` vs `domains.custom`+reconcile paths, and detaching. Read before instructing a user on custom-domain DNS.

When and how to give an app persistent disk: choosing a volume vs the managed database, declaring named-volume `mounts` in .deploymill/project.json and reconciling them, the write-under-mountPath rule, why volumes are per-app (no shared volumes — share via a service), how previews get their own fresh volume, and removing/renaming a volume. Read before persisting files to disk.

How PR previews are created, hostname derivation (auto-generated vs wildcard-domain-base), and the shared-prod-database gotcha. Read this before doing destructive migrations on a PR branch.

Enabling rollback via `.deploymill/project.json`, performing an image-swap rollback with `list_deployments` + `rollback`, what rollback does NOT cover (migrations, env vars, data), and when to use it vs forward-fix.

The health-endpoint contract: every web app exposes one endpoint (default /healthz) that returns 200 iff fully healthy; deploy/rollback/get_app_health and auto-rollback all key off it (200 = good, anything else = roll back). Covers the `health` block in .deploymill/project.json (path/retries/intervalMs/timeoutMs), strict vs lenient probe semantics, the N-consecutive-failure rule, the 404 fallback, the orchestrator Swarm HEALTHCHECK, and how to write real readiness checks into the handler. Read before relying on auto-rollback.

How `set_env_vars` / `list_env_vars` / `delete_env_vars` work: merge-vs-replace semantics, `${{project.X}}` template references, the redeploy-required rule, and the previews-share-prod-env consequence.

Where a project's files live and how the storage backend is modeled as a provider-neutral primitive: the file tools (push_files/get_file/list_files), the optional `source` block in .deploymill/project.json, and how a non-GitHub backend (e.g. self-hosted Gitea) would slot in without changing any tool.

How to store org-scoped secrets in the encrypted vault (`request_secret` browser hand-off — values never cross the agent) and get them into apps — `bind_secret` for one-offs or the `secrets` array in `.deploymill/project.json` + `reconcile_project` for config-as-code. Covers what encryption does and doesn't protect, the redaction guarantees, and wiring an app's Google OAuth (client id/secret + redirect URI).

Best practices for adding user accounts / login to a deploymill-managed app: the four platform facts (sessions in Postgres not on the ephemeral disk, host-pinned base URL per environment, signing/OAuth secrets through the vault, Secure cookies need HTTPS), the Node paved road (Better Auth on the managed Neon DB), the Python and hosted-IdP equivalents, and per-preview auth wiring (`${PREVIEW_URL}` base URL + OAuth redirect URIs).

How to read build/deploy logs (`source: "build"`) and runtime container stdout/stderr (`source: "runtime"`) with `get_logs` — `tail`/`grep`/`level`/`since` filtering, when to use which source, the failed-deploy debugging loop, and the runtime source's opt-in log-reader sidecar (degrades to `{ configured: false }` when absent).

Step-by-step playbook an agent follows after `reconcile_project` provisions a Postgres database for a Node/Hono app: add pg, build a pooled DB module, add a /db health route, scaffold node-pg-migrate, and run migrations at container start.

Step-by-step playbook an agent follows after `reconcile_project` provisions a Postgres database for a Python/FastAPI app: add psycopg + alembic, build a pooled DB module, add a /db health route, scaffold migrations, and run them at container start.

Step-by-step playbook an agent follows after `reconcile_project` provisions an R2 bucket for a Node/Hono app: add @aws-sdk/client-s3, build an S3 client from the injected S3_* env vars (R2 endpoint + forcePathStyle), upload/list/serve objects, and what NOT to do (don't park blobs on a volume, don't commit credentials).

Step-by-step playbook an agent follows after `reconcile_project` provisions an R2 bucket for a Python/FastAPI app: add boto3, build an S3 client from the injected S3_* env vars (R2 endpoint + path-style addressing), upload/list/serve objects, and what NOT to do.