Documentation
Set up Dockplane and connect your Docker hosts.
How a Dockplane deployment is put together, how the first host joins it, and where the documentation for the rest of it lives.
Where the documentation lives
The documentation is written once, in the repository, beside the code it describes. This page is an index of it, generated from those files on every build — so a page that is added, renamed or rewritten is reflected here, and nothing on this site can quietly drift out of step with what Dockplane actually does.
01Deployment
One control plane, one agent per Docker host.
The control server holds identity, authorization, inventory and audit history. Each managed Docker host runs an agent that performs the host-local work.
- Agents connect outbound to the control server, so no inbound management port is required on every Docker host.
- Production deployments require TLS.
- The public website is deployed separately and does not depend on a running control server.
Deployment topology
Control plane host├── Caddy 80, 443├── control server not published└── PostgreSQL not publishedDocker host A└── Dockplane agent ──┐Docker host B└── Dockplane agent ──┤ │ outbound, mutual TLS, 944302First host
Adding a host is one command.
The command carries a short-lived ticket, not a permanent credential. The agent exchanges a one-time token for a device identity, generated on the host, that can be revoked on its own. The private key never leaves the machine.
Connect a Docker host
- Sign in and open Hosts → Add host.
- Copy the command and run it on the Docker host.
- The agent package is downloaded and its checksum verified.
- The agent generates its key pair and enrolls.
- The service starts and connects outbound.
- The host appears with its containers and Compose projects.
03Reference
What the documentation covers.
Maintained alongside the source, describing behaviour that exists rather than planned functionality.
Getting started
What Dockplane is, how to install it, and how to connect a Docker host.
- OverviewDockplane is a self-hosted control plane for managing Docker across multiple hosts.
- InstallationDockplane is two things to install: a control plane, and an agent on each Docker host you want to manage.
- Add a HostA Docker host joins Dockplane by enrolling an agent. One command does all of it: it works out what the machine is, downloads the agent package matching this control plane, checks it against the checksums published with that release, installs it, enrolls the host and starts the service.
Operations
Running it: upgrades, backups, the agent, and what to check when something is wrong.
- UpgradingThe installer is the upgrade. Download the release, check it, unpack it, run it. There is one supported path and this is it.
- Backup and RecoveryA Dockplane control plane is three things, and a backup that has fewer than all three is not a backup:
- The AgentThe agent runs on each managed Docker host, natively under systemd. It is deliberately not a container: it manages the Docker daemon it runs beside.
- Container OperationsDockplane can start, stop and restart a container it has discovered, and can create, change and remove a container it manages itself. Together with the stack operations in Stacks, these are the only things that change a managed host.
- Container LogsDockplane can read what a container has printed, and follow it as it prints more. That is the whole of it: there is no console, no shell and no way to send anything to a container.
- TroubleshootingThe agent logs structured JSON to standard error, so journalctl -u dockplane-agent is the first place to look. Every line carries an event field; the ones named below are what to search for.
- Archiving HostsA machine that has been replaced, or an enrolment that has been superseded, stops being somewhere you work and stays somewhere you look things up. Archiving is how Dockplane records that.
- RecoveryThree things must survive a control-server loss, and they are deliberately kept apart. A backup of only one of them is not a backup.
- Building a ReleaseA Dockplane release has two halves, built by one command each: the control plane images, and the agent packages.
- StacksA stack is a Compose file, the environment it needs, and the host it belongs to. Dockplane keeps the whole history of what a stack has been configured to be.
- VersionsWhat an installation is running, where to see it, and the one thing Dockplane will ask the outside world if you let it.
Security
Trust boundaries, how a host proves who it is, and how operators sign in.
- Security ModelDockplane crosses:
- Agent EnrollmentEnrollment is how a Docker host obtains its own identity. An administrator issues a short-lived token, the host exchanges it once for a client certificate, and the token is spent in the process.
- AuthenticationDockplane authenticates operators against local accounts and keeps session state on the server.
- Vulnerability AssessmentEvery release is scanned and the report for each artefact is published as a release asset: both control-plane images on both architectures, and — from 0.3.0 — the agent binary on both architectures. This page is the assessment behind those numbers: what is in them, what was fixed, and why what remains is still there.
Reference
Architecture, supported platforms, limitations, and the agent interfaces.
- ArchitectureWhat a running Dockplane looks like. Every arrow is a connection something opens; nothing reaches into a managed host.
- Supported PlatformsSupported means the installer accepts it and this project tests on it. Nothing below is listed because it is likely to work.
- Known LimitationsWhat this release does not do. Some of these are decisions and will not change; the rest are simply not built yet. No dates are promised for either.
- Agent ProtocolThe protocol between the control server and an agent. It is not a remote shell protocol and has no message that carries a command.
- Agent GatewayThe agent gateway is a separate TLS listener from the browser API. Agents connect to it and are required to present a client certificate; browsers connect to the API and are not.
- Agent IdentityEvery Dockplane agent has its own cryptographic identity. There is no shared secret, no global agent key and no credential that can be copied between hosts without being detectable and revocable on its own.
- Interface VersionsFour numbers decide whether two pieces of Dockplane can work together. A change to any of them is a deliberate act with a migration story, not something that happens because a struct was edited.
- Compose SupportDockplane reads Compose files with the Compose specification's own library and turns them into a typed deployment plan. Everything a Compose file can express that Dockplane does not deploy is refused rather than ignored: a file that asks for something unsupported is an error, not a deployment quietly missing part of what its author configured.
Read the security model before connecting a host.
Docker daemon access is privileged. The security model describes the trust boundaries, the enrollment lifecycle and what the agent is allowed to do.