Docker

Every site has a Docker tab. It walks you through three steps — 1 Docker engine (where the containers run while you test), 2 Docker files (the ones Dokploy or Coolify deploy later) and 3 Test in containers (Build & Up, the containers and their names) — with an optional Development services in Docker section at the end. Docker lives only in the site tab; there is no Docker section in the rail.

The Docker tab works on macOS and Windows.

1 · Docker engine

Step 1 is where your containers run while you test them. It offers two choices:

• DoCatz — recommended. DoCatz is the Catzoid container engine, and every container gets a name: https://<service>.<project>.docatz.<tld>, with no change to your Dockerfile or compose file. DevCatz talks to it through its own docatz context, so your computer’s current Docker context is never switched.
• The current Docker context of your computer — whatever engine it points at.

Each engine shows its state (running, starting…, not running · click to start it); clicking a stopped one starts it and picks it. The choice is kept in Settings. Until you pick otherwise, DevCatz uses DoCatz whenever DoCatz’s engine is running. The tab checks again every few seconds.

DoCatz not installed? Pick it, or press Open in DoCatz, and DevCatz offers Download & Install: it fetches the latest DoCatz release from GitHub, checks its checksum, puts DoCatz in Applicationsruns its installer just for you (no administrator rights) and opens it at your compose file. With no engine at all, the tab says No container engine installed and offers DoCatz first, with links to the others. Any Docker-compatible engine works.

Open in DoCatz shows this site’s containers in DoCatz. It is greyed out while the containers run on another engine — pick DoCatz in step 1 to see them there.

2 · Docker files

Step 2 writes the files Dokploy and Coolify deploy, for the stack DevCatz detected: a multi-stage Dockerfile per app, docker-compose.yml (the file Dokploy and Coolify read by default — no compose path to change, just attach the domain to the web service) and .dockerignore. Generate Docker files… (or Regenerate Docker files…) shows every file before anything is written.

Your own Docker setup comes first. When the project already has a compose file that builds the app, the step says This project has its own Docker setup, lists each file and what it builds, and links straight to step 3 to test it — those are the files Dokploy already deploys, so change them in the editor below. The generator becomes Generate new files anyway…: it warns that these are DevCatz’s standard files for the stack, not a copy of yours, and ticks nothing.

DevCatz finds compose files (compose.yml, docker-compose.yml, docker-compose.<name>.yml) in the project’s root and one level down in docker/, deploy/, .docker/, infra/ and ops/. In a folder-layout project each file says which apps it builds — every app for one compose file that builds the whole monorepo, or web, api.

Options

The files publish no ports: on your computer DoCatz (or OrbStack) names each container, and on the server Dokploy routes the domain.

The preview

Open a file to read the diff or edit it, Reset to go back to the generated version, then Write selected files. Replacing an existing file asks first.

The Docker files card

Docker files lists the Docker files in the project — the root, each app’s folder, docker/, deploy/ and the rest. Open → reads or edits one (mod+S saves, Revert throws your edits away). Regenerating later asks before replacing a file you changed.

3 · Test in containers

Pick the compose file (docker-compose.yml · every app, · web, api, (generated) …), then:

While a command runs, a progress panel shows the phase (Building images…, Starting containers…), the time, each service’s build step, each container’s state and the latest line, with Open Logs and Cancel. Cancel ends compose and what it started; containers already made stay, and Down removes them. One compose command runs per site at a time — the buttons stay off until it ends, also when it was started from Build ▾ or when you come back to the tab mid-run. A failure opens the Logs tab.

The table lists each service with its State (and health), its URL — the DoCatz or OrbStack name, else http://localhost:<port>; databases, Redis, workers and schedulers get none — and its own Restart and Logs. Once it runs well, the step says what is left: commit and push docker-compose.yml and the Dockerfiles, and in Dokploy create a Compose service from the repository — with a button to the Git tab.

Your .env inside the containers

Inside a container 127.0.0.1 is the container itself, so before every run DevCatz hands each service your .env with the hosts on your computer pointed at host.docker.internal: *_HOST set to 127.0.0.1, localhost or ::1, and database, Redis, queue and mail URLs on those addresses. APP_*, ASSET_* and VITE_* keys are left as they are, your .env file is not changed, and the compose file’s own environment: wins.

On DoCatz, each compose project has its own .env kept in DoCatz (like a deploy platform’s Environment settings). The line Environment: says which one the containers get:

• DoCatz’s .env of <project> — marked same as the project’s .env, or differs from the project’s .env (DoCatz’s is used) with Replace with the project’s .env… (asks first; what you changed in DoCatz is lost);
• the project’s .env — copied to DoCatz on the first Build & Up, then kept: change it in DoCatz;
• none — the project has no .env.

An existing DoCatz .env is never replaced on its own.

Worktrees and Dokploy’s network

Each worktree site runs beside the main site: it always gets its own compose project (feat-x-shop), a fixed container_name gets the worktree’s name added, and fixed published ports are left out — through a small override for that run, never by changing your compose file.

A compose file that joins the external dokploy-network still runs here: when the network is missing, DevCatz creates it on the engine and runs Up again.

From the site header

When the site has a compose file, Build ▾ at the top has a Docker Compose group: Build & Up and Down for each compose file, and Docker tab. They run in the Docker tab, so its progress panel shows. Start runs only the site itself; containers start from step 3 or Build ▾.

Development services in Docker

Optional, at the end of the tab: databases and helpers for development, in docker-compose.dev.yml, while the site itself keeps running in DevCatz. Create docker-compose.dev.yml… (or Change…) offers PostgreSQL, MySQL or MariaDB, Redis, MongoDB, Mailpit and Meilisearch — marked used when the project seems to use them. Each is published on 127.0.0.1, on its usual port when it is free, otherwise on one from a pool starting at 4800; passwords come from your .env, with healthchecks and volumes that are kept. Then Up starts them, and Use in .env… previews and writes DATABASE_URL / DB_*, REDIS_*, MONGODB_URI, MAIL_* / SMTP and MEILISEARCH_* pointing at them.

Desktop apps

An Electron or Tauri app has no deploy files: its Docker tab is Containers plus the development services, open by default. The generators say how such apps ship instead — electron-builder or Electron Forge for Electron, cargo tauri build for Tauri.

What the generators know

They also handle SQLite databases, folder-layout projects with several apps, and a project that already has its own Dockerfile.

Explain the last Docker output

When a build or up fails, ✦ Explain the last Docker output sends the output to your AI provider and comes back with what went wrong and how to fix it. It needs AI on, with its Docker feature switched on; secrets in the output are masked first.

The same feature adds ✦ Edit with AI to a Docker file you open: say in plain words what to change, and the result lands in the editor for you to check before you save. Together these send the compose / build log and the file you adjust — nothing else.

Limits

• OrbStack, Colima and Finch exist for macOS only. On Windows, use DoCatz, Docker Desktop, Rancher Desktop or Podman Desktop.
• On Windows the Docker gateways always run in DoCatz, whatever engine this tab uses.
• The generated files are a solid start, not a guarantee: read the preview before you deploy.

Last updated 2026-11-02