Quickstart

This guide installs Docker Manager and its agent on one server. It takes about ten minutes.

1. Create the filesCopy Anchor Link

Make a folder for Docker Manager and go into it:

mkdir -p /opt/docker-manager && cd /opt/docker-manager

Create a file named compose.yaml with this content:

name: docker-manager

services:
  docker-manager:
    image: registry.neureka.dev/docker-manager/docker-manager/manager:edge
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      DOCKER_MANAGER_PUBLIC_URL: ${DOCKER_MANAGER_PUBLIC_URL}
      DOCKER_MANAGER_TRUSTED_PROXIES: ${DOCKER_MANAGER_TRUSTED_PROXIES}
    volumes:
      - data:/var/lib/docker-manager
    labels:
      docker-manager.role: manager
    networks:
      - docker-manager

  docker-agent:
    image: registry.neureka.dev/docker-manager/docker-manager/agent:edge
    restart: unless-stopped
    privileged: true
    cgroup: host
    pid: host
    stop_grace_period: 2m
    depends_on:
      - docker-manager
    environment:
      DOCKER_AGENT_MANAGER_URL: http://docker-manager:8080
      DOCKER_AGENT_MANAGER_ALLOW_HTTP: "true"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
      - stacks:/var/lib/docker/volumes/docker-manager_stacks/_data
      - agent:/var/lib/docker-agent
      - .:/import/docker-manager:ro
    labels:
      docker-manager.role: agent
    networks:
      - docker-manager

networks:
  docker-manager:
    name: docker-manager

volumes:
  data:
  agent:
  stacks:

Then create a file named .env next to it:

# The address you will open Docker Manager at. It must start with https://
DOCKER_MANAGER_PUBLIC_URL=https://docker.example.com

# The address of your reverse proxy. This value fits a proxy that runs on
# this server. If your proxy runs on another server, put that server's
# IP address here instead, for example 192.168.1.10.
DOCKER_MANAGER_TRUSTED_PROXIES=172.16.0.0/12

Replace docker.example.com with your own domain name.

2. Start itCopy Anchor Link

docker compose up -d
docker compose ps

After a minute, both containers show as running and healthy.

3. Put HTTPS in front of itCopy Anchor Link

Docker Manager listens on port 8080 of your server, over plain HTTP. Point your reverse proxy at it, so that your domain name opens Docker Manager over HTTPS. If your proxy runs in Docker on this server, you can instead connect it to the docker-manager network and point it at http://docker-manager:8080.

Your proxy must:

• use a certificate your browser trusts,
• speak HTTP/2 to browsers,
• allow WebSocket connections,
• keep idle connections open for at least 60 seconds,
• allow uploads as large as Docker Manager's upload limit (53.69 GB by default), or set no limit on the request body size,
• pass on the original host name and forwarded headers. Most proxies do this by default.

4. Create your accountCopy Anchor Link

Open your address, for example https://docker.example.com.

Choose a username and a password of at least 15 characters, then press Create Owner Account. Then add an authenticator app or a passkey under Profile (see Users & Groups).

5. Connect this serverCopy Anchor Link

1. Open Environments and press Add Environment.
2. Give it a name if you like (without one, the server's name is used), and press Create Install Command.
3. Open the On the Docker Manager Server tab and copy the command.
4. Run it on your server, in the folder with your compose.yaml (/opt/docker-manager).

The page shows Connected within a few seconds. If you leave the page before, Docker Manager asks first: the command can't be shown again, but it keeps working until it expires. Your server now appears with its containers, images, volumes and networks. Next, press Create Stack to create your first stack, or Import Projects to take over the Compose projects already on the server (the button shows how many it found).

Until everything is set up, the Dashboard shows a Getting Started list: add an environment, create or import a stack, set up backups, add a notification channel and set up two-factor sign-in. Each step has a button that takes you there and is checked off when done; creating or importing a stack waits until you have an environment. The list goes away when all are done; Hide folds it into one line in this browser, and Show brings it back.

Add more serversCopy Anchor Link

Every other server you want to manage needs its own agent. It connects to your Docker Manager address over HTTPS and needs no open ports.

1. In Docker Manager, open Environments → Add Environment, give it a name if you like and press Create Install Command. The command works once and expires after one hour (change it under More Options → Command Expires After, up to 24 hours).
2. Start the agent in one of two ways:
   • Single command: copy the command from the On Another Server tab and run it on the new server.
   • Compose: make a folder such as /opt/docker-manager on the new server and create the compose.yaml below. Copy the lines that start with DOCKER_AGENT_ from the On Another Server, with Compose tab into a .env file next to it, and run docker compose up -d.

name: docker-manager

services:
  docker-agent:
    image: registry.neureka.dev/docker-manager/docker-manager/agent:edge
    restart: unless-stopped
    privileged: true
    cgroup: host
    pid: host
    stop_grace_period: 2m
    environment:
      DOCKER_AGENT_MANAGER_URL: ${DOCKER_AGENT_MANAGER_URL}
      DOCKER_AGENT_ENROLLMENT_TOKEN: ${DOCKER_AGENT_ENROLLMENT_TOKEN:-}
      DOCKER_AGENT_ENVIRONMENT_NAME: ${DOCKER_AGENT_ENVIRONMENT_NAME:-}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
      - stacks:/var/lib/docker/volumes/docker-manager_stacks/_data
      - agent:/var/lib/docker-agent
      - .:/import/docker-manager:ro
    labels:
      docker-manager.role: agent

volumes:
  agent:
  stacks:

DOCKER_AGENT_MANAGER_URL=https://docker.example.com
DOCKER_AGENT_ENROLLMENT_TOKEN=dye_...

The page shows Connected within a few seconds. You can then remove the DOCKER_AGENT_ENROLLMENT_TOKEN line; it works only once anyway. If the server doesn't connect, see Troubleshooting.

Good to know:

• One Docker server can have only one agent. To reconnect a server Docker Manager already knows, use Re-Attach (see Environments).
• For a cloned virtual machine, check This Server Is a Clone of a Connected Server under More Options before you create the command.
• Unused commands are listed under Waiting for an Agent on the Environments page. Revoke cancels one.
• If the command expired or was revoked before the server connected, press Create New Command. The name and options you chose stay.

UpgradeCopy Anchor Link

Docker Manager upgrades itself from the app, like any other stack.

1. Once: open Stacks → Import Projects, pick this server's Environment (only when you have more than one) and press Import next to docker-manager. It keeps running while it is imported.
2. To upgrade: open the docker-manager stack and choose Pull and Deploy in the menu next to Deploy.
3. The app shows A new version of Docker Manager is available. Press Reload to Upgrade.

Good to know:

• From now on, change Docker Manager's files in the stack's Files tab. After the first deploy it runs from its copy in /var/lib/docker/volumes/docker-manager_stacks/_data/docker-manager, and /opt/docker-manager is no longer used.
• Upgrade Docker Manager first, then your other servers: import each server's docker-manager project the same way and use Pull and Deploy on it.
• Pull and Deploy restarts the agent only when it gets a new version or changed settings. It does so once the other jobs on its server, such as a backup or a restore, are done; jobs started meanwhile show Waiting for the Docker Agent to restart. and start after it. Cancel Job ends a waiting job right away. If other jobs still run after 3 hours, the agent keeps its version: use Pull and Deploy again later.
• To upgrade automatically, keep these stacks covered in the update settings.
• If you installed Docker Manager before its charts had a reading every second, add cgroup: host and pid: host to each server's agent, as in Metrics. Until then its charts say Readings Every 10 s.
• An agent you started with the single command is not a Compose project, so it can't be upgraded from the app. Set it up with Compose instead.
• Before Docker Manager changes its database for a new version, it saves a copy. If an upgrade fails, see Troubleshooting.