Dockplane 0.2.0

Dockplane 0.2.0

The second stable release.

Dockplane now runs workloads rather than only watching them. You write a
Compose file in Dockplane, save it, and deploy it to one of your hosts.
Dockplane owns what it created: it knows which containers belong to that stack,
which revision they are, and how to take them away again. Everything 0.1.0 did
— the inventory, the agents, the audit trail — it still does.

Highlights

Stacks. A Compose file, saved in Dockplane and deployed to a host. Every
save is an immutable revision, so what is saved and what is running stay two
separate facts and the interface never conflates them. A stack with changes
that are saved but not deployed says so; a stack whose host does not match any
complete revision says that instead, and stops.

Any revision, forwards or back. Applying revision three to a stack running
revision five is a rollback, and it is named that way. Dockplane converges the
host on whichever revision you chose.

Secrets that stay secret. A stack's environment can hold secrets. They are
encrypted at rest under the deployment's own key — not the database's — and
travel to the host inside the deployment plan. They appear in no log, no audit
entry and no API response. Dockplane shows that a secret is set; it will not
show you what it is.

Start, stop, restart. A deployed stack moves between running and stopped
without being redeployed, in dependency order, and the result is read back off
the host rather than taken from the agent's word for it.

Delete. A stack's service containers are removed and its saved
configuration and revision history are deleted. Named volumes are kept, and
no data in them is deleted. A deployed stack has to be named back before the
action is offered, and a stack whose host state is unclear cannot be deleted at
all.

Containers you create by hand. A single container can be created,
reconfigured and removed from the interface. Reconfiguring recreates it on
Docker's side, and it stays the same container in Dockplane — same identity,
same history, same audit trail. Creating one lists every host and says which of
them can be chosen: a host whose agent is offline is shown and cannot be
selected, with the reason given before the form is filled in.

Compose that says no. A file is compiled and checked before it can be
saved. Anything Dockplane will not deploy is refused with the path in the file
and a sentence saying why, rather than deployed with that part quietly missing.
See Compose Support.

A host is named by the name you gave it. A machine enrolled more than once
leaves a host resource behind for every enrolment, and every one of them reports
the same system hostname. The name you chose leads and the system hostname
follows it, everywhere a host appears. Nothing is merged and nothing is
deduplicated: they are separate hosts, and they look it.

Last known means last known. A host that stops answering marks its readings
as the last ones at once, and its containers and Compose projects do the same.
Its CPU, memory and disk are kept and labelled with when they were reported
rather than dropped, a container whose host went quiet still opens and shows the
last state seen, and opening its logs says the live stream is unavailable rather
than reporting an operation that was not carried out. A stack on an offline host
says what that does and does not prevent: configuration and new revisions can be
saved, and deploying waits for the host to come back.

Enrolment is one command. Dockplane produces it, and 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, enrols the host
and starts the service. The agent holds its own certificate, obtained once with
a short-lived ticket, and connects outward over mTLS; nothing needs to reach
into the managed host.

Releases can be rebuilt. Building this release from its own commit produces
the same images and the same agent packages, on a different machine and at a
different time, so a published artifact can be checked against a build of the
source it names. What a build records about itself — its provenance attestation
— still describes that build.

Security

No remote shell. The agent has a fixed catalog of typed capabilities and no
way to run anything else. Stacks are capabilities like the rest —
stack.deploy, stack.start, stack.stop, stack.restart, stack.remove —
each carrying a resolved plan. No Compose file, YAML parser, Compose CLI or
command string reaches a managed host. Compose is read in one place, the control
server, and nowhere else.

• Dockplane touches only what it can prove is its own. Every container,
  volume and network it creates carries its identity. An operation that finds a
  container it cannot prove belongs to the stack it was asked about stops rather
  than acting, and a deployment refuses a volume or network carrying somebody
  else's.
• A half-applied stack blocks rather than guesses. If the host does not
  match one complete confirmed revision, the stack needs attention and nothing
  further is applied, operated or deleted until a person chooses a revision.
• An operation whose result never came back is not repeated. The stack stays
  blocked, and the next complete reading of that host settles what happened.
• Deleting a stack is not deleting its data. Named volumes are kept, and a
  new stack of the same name will not adopt them.
• Destructive actions carry their own permissions, need the resource named
  back, and are recorded with actor, target, result and request identifier.

Three permissions that guarded nothing — roles.manage, stacks.adopt and
stacks.secrets.reveal — were removed from the catalog. They could be granted
and conferred nothing, which is worse than not existing.

See Security Model,
Agent Security and
Authentication.

Installation

Ubuntu 24.04, Ubuntu 22.04 or Debian 12, with Docker Engine and the Compose
plugin:

VERSION=0.2.0

sha256sum -c SHA256SUMS
tar xzf "dockplane-$VERSION.tar.gz"
cd "dockplane-$VERSION"
sudo ./install-control-plane.sh --domain dockplane.example.com

Then sign in and add your first host. See
Installation and
Add a Host.

Upgrading

The installer is the upgrade: download the release, check it, unpack it, run
it. It takes a backup and validates it before anything changes, and stops if
either fails. Pulling images and editing .env is not an upgrade path.

Upgrading from a 0.2.0 release candidate changes no schema. Upgrading from
0.1.0 migrates it.

Upgrade the control plane first, then the agents. While a fleet is
half-upgraded, everything 0.1.0 could already do goes on working on every host,
and an operation this release added is refused on a host whose agent has not
been upgraded yet — with This host does not support that operation. Nothing is
changed on that host and nothing is recorded as if it had been. See
Upgrading.

Supported platforms

Control plane	Ubuntu 24.04, Ubuntu 22.04 or Debian 12, amd64
Managed hosts	Debian 12, Ubuntu 24.04 or Ubuntu 22.04 with systemd

Ports: 80 and 443 for browsers, 9443 for agents. The API and PostgreSQL are not
published. See Supported Platforms.

ARM64

experimental — built and inspected, not runtime-tested

Packages, binaries and images are produced for arm64 and inspected, and no
arm64 machine has run them. Use amd64 in production.

Known limitations

Read Known Limitations before deploying.
In short:

• There is no remote shell, exec or attach, and no generic command
  execution on a managed host.
• Compose projects discovered on a host are read-only and cannot be taken over.
• build: is refused: Dockplane deploys images, it does not build them.
• There is no automatic update, no self-updater, no APT repository, and no Git
  or webhook integration.
• There is no downgrade path.
• Re-enrolling a machine creates a new host record; the old one stays behind and
  nothing is merged automatically.
• An agent must reach the control plane at the hostname it was enrolled with.
• Applying a revision recreates every service, so a stack is briefly down while
  it is rebuilt.
• A stack's networks are not removed when it is deleted, volumes are never
  removed, and a volume left behind by a deleted stack is not reused by a new
  one.
• A rollback deploys an earlier configuration; it does not restore data.
• A stack secret cannot be read back.
• Volume deletion and image management are not implemented.
• Notifications, alerting and scheduled automation are not in this release.
• Backups are not encrypted by Dockplane, and images are not signed.
• Container output is not stored; logs are read from the host when you ask for
  them.
• arm64 is experimental, as above.

License

AGPL-3.0-only. See LICENSE.