Docker API Permissions¶

Doco-CD needs access to the Docker API to deploy your stacks. By default this is the mounted Docker socket, which grants unrestricted control over the host.

If you would rather place a Docker socket proxy in front of the daemon, this page documents which Docker API endpoints doco-cd actually uses, so you can grant only what your setup needs.

Required endpoints per feature¶

The tables below list the Docker Engine API endpoints doco-cd calls, grouped by feature. Paths are shown without the /v1.x API version prefix that the client prepends to every request.

Always required¶

Every doco-cd installation needs these, regardless of the deployment mode.

Docker Compose deployments¶

Docker Swarm deployments¶

Used instead of most Compose endpoints when the daemon is a Swarm manager.

Optional features¶

These endpoints are only needed when the corresponding setting is enabled.

SCHEDULER_ENABLED endpoint details¶

• Default (execution_mode: restart): POST /containers/{id}/restart; Swarm: GET /services/{id}, POST /services/{id}/update
• execution_mode: one_off: POST /containers/create, POST /containers/{id}/wait, POST /containers/{id}/start; Swarm: POST /services/create, DELETE /services/{id}, GET /tasks
• stop_services: POST /containers/{id}/stop|start; Swarm: POST /services/{id}/update, GET /tasks

REST API endpoint details¶

• Compose project management: GET /containers/json, POST /containers/{id}/start|stop|restart, DELETE /containers/{id}, DELETE /networks/{id}, DELETE /volumes/{name}, DELETE /images/{name}
• Swarm stack/service management: GET /services, POST /services/{id}/update, DELETE /services/{id}, DELETE /configs/{id}, DELETE /secrets/{id}

Building images¶

If any of your services use build: in their compose file, you additionally need POST /build (and POST /session when BuildKit is used).

Never used¶

Doco-CD does not call these endpoints, so you can safely deny them:

POST /auth, POST /commit, POST /containers/{id}/exec, POST /exec/{id}/start, GET /containers/{id}/logs, GET /containers/{id}/top, POST /containers/{id}/pause, GET /plugins, GET /system/df, POST /swarm/init, POST /swarm/join

Example socket proxy configuration¶

The following example uses tecnativa/docker-socket-proxy, which maps Docker API resources to environment variables.

services:
  dockerproxy:
    image: ghcr.io/tecnativa/docker-socket-proxy:latest
    environment:
      # Required by every installation
      PING: 1
      VERSION: 1
      INFO: 1
      EVENTS: 1
      CONTAINERS: 1
      IMAGES: 1
      NETWORKS: 1
      VOLUMES: 1
      DISTRIBUTION: 1
      # Docker Swarm only, omit these on a standalone daemon
      SERVICES: 1
      TASKS: 1
      NODES: 1 # (1)!
      SECRETS: 1
      CONFIGS: 1
      # Required to deploy anything
      POST: 1
      DELETE: 1 # (2)!
      # Endpoints doco-cd never uses
      AUTH: 0
      BUILD: 0
      COMMIT: 0
      EXEC: 0
      PLUGINS: 0
      SESSION: 0
      SWARM: 0
      SYSTEM: 0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

  doco-cd:
    image: ghcr.io/kimdre/doco-cd:latest
    container_name: doco-cd
    depends_on:
      - dockerproxy
    environment:
      DOCKER_HOST: tcp://dockerproxy:2375 # (3)!
      WEBHOOK_SECRET: xxx
    ports:
      - "80:80"
    volumes:
      - data:/data # (4)!
    cap_drop:
      - ALL
    restart: unless-stopped

volumes:
  data:

1. Needed to wait for Swarm services to converge. Without it every Swarm deployment fails with 403 Forbidden.
2. Required for recreating containers, rotating configs/secrets and remove_orphans. Set to 0 only if you accept that redeployments will fail.
3. Point doco-cd at the proxy instead of mounting the socket. See Docker Settings.
4. The Docker socket is no longer mounted here — only the data volume remains.

Minimal standalone (Compose only) configuration¶

If you do not use Docker Swarm, drop the Swarm resources:

services:
  dockerproxy:
    image: ghcr.io/tecnativa/docker-socket-proxy:latest
    environment:
      PING: 1
      VERSION: 1
      INFO: 1
      EVENTS: 1
      CONTAINERS: 1
      IMAGES: 1
      NETWORKS: 1
      VOLUMES: 1
      DISTRIBUTION: 1
      POST: 1
      DELETE: 1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Troubleshooting¶

If a deployment fails with a 403 Forbidden error such as:

failed to deploy stack myapp: Error response from daemon:
<html><body><h1>403 Forbidden</h1>
Request forbidden by administrative rules.
</body></html>

your proxy is blocking an endpoint that doco-cd needs. Most socket proxies log the rejected request, so check the proxy logs to find the exact method and path, then look it up in the tables above.

The most common causes are: