Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Nettalco/dokploy/llms.txt

Use this file to discover all available pages before exploring further.

Dokploy has native support for Docker Compose, letting you manage the full lifecycle of multi-container stacks — web servers, databases, workers, caches — using the same docker-compose.yml format you already know. Compose stacks can be sourced from a Git repository, pasted in as raw YAML, or bootstrapped from one of Dokploy’s built-in templates, and every service in the stack gets its own log stream and status indicator in the dashboard.

​
How It Works

When you deploy a Compose stack, Dokploy:
  1. Clones the repository (or reads the inline YAML) to a working directory on the server.
  2. Optionally applies environment variable substitution from the stack’s Env configuration.
  3. Runs docker compose up -d (or docker stack deploy in Swarm mode) to bring all services up.
  4. Monitors each service individually and surfaces per-service logs and container status in the dashboard.
Updates follow the same flow: a new commit triggers a docker compose pull && docker compose up -d sequence, replacing containers with zero-downtime where the image and restart policy allow.

​
Creating a Compose Stack

1

Open a project

Navigate to the project where you want to deploy the stack.
2

Add a Compose service

Click Add Service and choose Docker Compose.
3

Name the stack

Give it a Name and an optional description. Dokploy generates a unique appName used internally for service naming.
4

Choose a source

Select where the docker-compose.yml comes from: a Git repository, raw YAML, or a template (see Compose Sources below).
5

Configure the Compose path

If your docker-compose.yml is not in the repo root, set the Compose Path (default: ./docker-compose.yml).
6

Deploy

Click Deploy. Dokploy builds and starts all services defined in the file and streams the deployment logs in real time.

​
Compose Sources

Connect a GitHub, GitLab, Gitea, Bitbucket, or generic Git repository that contains a docker-compose.yml file. Dokploy clones the repo on every deploy and can automatically trigger a new deployment on every push via the Auto Deploy webhook.
Source type options:
  github    — OAuth app integration with GitHub
  gitlab    — OAuth app integration with GitLab
  gitea     — OAuth app integration with Gitea
  bitbucket — OAuth app integration with Bitbucket
  git       — Raw Git URL with optional SSH key
Set the branch and optionally the Compose path if the file is not at the repo root (e.g. ./infra/docker-compose.yml).
Enable the Watch Paths option to restrict deployments to only fire when specific paths in the repository change, reducing unnecessary rebuilds in monorepos.

​
Environment Variables

Open the Environment tab on a Compose stack to define variables that are substituted into the compose file at deploy time — equivalent to a .env file. 
# Example compose environment variables
POSTGRES_PASSWORD=supersecretpassword
APP_SECRET_KEY=changeme
DOMAIN=example.com
Reference them in your compose file using standard Docker Compose variable syntax: 
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  web:
    image: myapp:latest
    environment:
      SECRET_KEY: ${APP_SECRET_KEY}

​
Service Management

After a Compose stack is deployed, Dokploy parses the running containers and surfaces each service individually. From the Services tab you can:
  • View the status (running, stopped, error) of each service.
  • Open per-service logs to tail the output of a specific container.
  • Fetch the current service list on demand via the Load Services action.
Use the Compose Type setting to choose between docker-compose (for single-node deployments) and stack (for Docker Swarm multi-node deployments).

​
Domains and Routing

You can attach Traefik domains to individual services within a Compose stack. This is the standard way to expose a specific compose service to the internet.
1

Open the Domains tab

Navigate to the Compose stack and click the Domains tab.
2

Add a domain

Click Add Domain. Set the Host, Port, HTTPS toggle, and optionally the Service Name inside the compose file that should receive traffic.
3

Save

Dokploy generates the Traefik router and service configuration and writes it to the Traefik dynamic configuration directory. The domain becomes active immediately.
The Service Name field must match the service name as it appears in your docker-compose.yml (e.g. web, api). Dokploy prefixes it with the stack’s appName when constructing the Traefik rule.

​
Randomize Ports

Port conflicts can occur when multiple Compose stacks define hard-coded host port mappings. The Randomize Compose feature rewrites all published port mappings to randomly assigned available host ports, preventing conflicts between stacks. 
# Before randomization
ports:
  - "3000:3000"

# After randomization (example)
ports:
  - "31742:3000"
You can also use Isolated Deployment mode, which prefixes every service and volume name with the stack’s unique suffix — allowing you to run multiple independent copies of the same compose file on one server.

​
Import Existing Compose

If you already have a running Docker Compose stack on the server and want to bring it under Dokploy management without downtime, use the Import workflow:
  1. Create a new Compose service in Dokploy with the Raw YAML source.
  2. Paste in the compose file that matches the running stack.
  3. Dokploy attaches to the existing containers instead of replacing them.

​
Example: Web App + Database Stack

services:
  web:
    image: node:20-alpine
    working_dir: /app
    command: node dist/server.js
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/appdb
      PORT: "3000"
    depends_on:
      - db
    labels:
      - "traefik.enable=true"

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:
When using Traefik labels directly in your compose file (instead of Dokploy’s Domains tab), make sure the Traefik container has access to the Docker socket and the services share the same Docker network.

Build docs developers (and LLMs) love

Get started for freeTalk to us