Docker and Compose
DeaconGuard publishes a container image for every release:
ghcr.io/cloudopsshell/deaconguard:1.35.0
It's the same binary as the packages, for amd64 and arm64, on Chainguard's minimal static base image: no shell and no package manager, running as the non-root user nonroot (65532). Its entrypoint is deaconguard, so the container's command is a DeaconGuard command, such as serve … or agent run. The image is signed keyless like the release files, and carries its SBOM in the registry. Tags: the version, such as 1.35.0, the minor version, such as 1.35, and latest. Pin the exact version; https://get.deaconguard.io/stable.txt holds the latest.
Docker Compose
deploy/compose/compose.yaml runs the server, with its data in a volume:
mkdir deaconguard && cd deaconguard
VERSION=$(curl -fsSL https://get.deaconguard.io/stable.txt)
curl -fsSLO "https://raw.githubusercontent.com/Cloudopsshell/deaconguard/v${VERSION}/deploy/compose/compose.yaml"
printf '%s' 'a-long-password' > admin-password && chmod 600 admin-password && sudo chown 65532 admin-password
docker compose up -d
docker compose logs server
Compose mounts the file as it is, so it must be readable by the image's user, 65532, hence the chown. Open https://THIS-MACHINE:8443 and sign in as admin with that password (at least 12 characters). The server creates a self-signed certificate on its first start; the log shows its fingerprint. Then delete admin-password: it's only read while there is no account.
What the file sets up:
| Command | serve --listen 0.0.0.0:8443 --agent-listen 0.0.0.0:8444: the dashboard on 8443, and a port for agents on 8444 |
| First account | DEACONGUARD_ADMIN_USER=admin, with the password from the admin-password secret through DEACONGUARD_ADMIN_PASSWORD_FILE |
| Data | the data volume, at /home/nonroot (DEACONGUARD_HOME): the database, the certificate and the feed cache |
| Hardening | read-only root filesystem, no Linux capabilities, no-new-privileges |
Keep ports 8443 and 8444 away from the internet: see Securing the dashboard. "8443:8443" and "8444:8444" publish them on every address of the host, so other machines can reach them; that is how agents on other machines connect to 8444. Docker writes its own firewall rules for published ports, which ufw and firewalld don't filter, so limit them with a firewall in front of the host, such as a cloud security group. If no agent outside the host connects, publish the agent port on loopback only: "127.0.0.1:8444:8444".
Scan the Docker host too
The agent service, in the agent profile, scans the machine Compose runs on, not its container:
-
On the Agents page, choose Enroll a machine. As the server address, use
https://127.0.0.1:8444, and create the token. That works here because the agent runs withnetwork_mode: host: its127.0.0.1is the Docker host's, where Compose publishes the server's port 8444. For agents on other machines, use the host's address instead, such ashttps://10.0.1.5:8444. -
Save it next to
compose.yaml:printf '%s' 'deaconguard1.…' > enrollment-token && chmod 600 enrollment-tokendocker compose --profile agent up -d -
The machine appears on the Agents page under its host name. The agent keeps its identity in the
agentvolume, so it enrolls only once; deleteenrollment-tokenafterwards if you like.
The agent reads the host's root filesystem, mounted read-only at /host, and runs its checks there with the host's own tools: dpkg or rpm, sshd -T, sysctl, ss, ClamAV. So its results are the same as an agent installed on the host, and the host needs those tools installed for the checks that use them. For that, the container:
- runs as root, with the host's process list (
pid: host) and network (network_mode: host); - has only the capabilities the checks need:
SYS_CHROOTto run them in the host's root,DAC_READ_SEARCHandDAC_OVERRIDEto read every file,NET_ADMINandAUDIT_CONTROLto list firewall and audit rules,SYS_PTRACEto see every process, andBPFandPERFMONto load live detection's watchers into the kernel (1.27.0 and later); - mounts the host's
/tmpwritable at/host/tmp, where the advanced malware scan writes its rules for a moment.
Use your own certificate
Mount the certificate and key, and pass them to serve:
services:
server:
command: [serve, --listen, "0.0.0.0:8443", --agent-listen, "0.0.0.0:8444",
--tls-cert, /run/secrets/tls.crt, --tls-key, /run/secrets/tls.key]
secrets: [admin-password, tls.crt, tls.key]
secrets:
tls.crt: {file: ./tls.crt}
tls.key: {file: ./tls.key}
The files must be readable by user 65532. Agents enrolled earlier keep working when their system trusts the new certificate for the server's name; otherwise enroll them again.
Behind a reverse proxy
Add --trusted-proxy with the proxy's address or network to the command, or set DEACONGUARD_TRUSTED_PROXIES, so sign-in limits and the audit log see each browser's address instead of the proxy's. See Behind a reverse proxy.
Plain Docker
docker volume create deaconguard
printf '%s' 'a-long-password' > admin-password && chmod 600 admin-password && sudo chown 65532 admin-password
docker run -d --name deaconguard --restart unless-stopped \
-p 8443:8443 -p 8444:8444 \
-v deaconguard:/home/nonroot \
-v "$PWD/admin-password:/run/secrets/admin-password:ro" \
-e DEACONGUARD_HOME=/home/nonroot \
-e DEACONGUARD_ADMIN_USER=admin -e DEACONGUARD_ADMIN_PASSWORD_FILE=/run/secrets/admin-password \
--read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
ghcr.io/cloudopsshell/deaconguard:1.35.0 serve --listen 0.0.0.0:8443 --agent-listen 0.0.0.0:8444
The volume must be mounted at /home/nonroot: the image's user owns that directory, so a new volume there is writable without root.
Manage the server
Commands run in the container, as its user, with its data directory:
docker compose exec server deaconguard user list
docker compose exec server deaconguard user passwd admin
docker compose exec server deaconguard token create --server-url https://HOST:8444 --reusable --days 30
Upgrade, back up and remove it as described in Upgrade, Back up and restore and Uninstall.