Install with Docker Compose¶

Version française

Choose the minimal agent, add its web UI, or use the separate Prometheus/Grafana stack. None of these installations enables automatic container actions by default.

Need	Compose files	Local address
Agent and API	`docker-compose.yml`	`http://127.0.0.1:9808`
Agent and web UI	Base plus `docker-compose.ui.yml`	`https://localhost:8443`
Metrics history and dashboards	`examples/monitoring/compose.yaml`	Grafana on `http://127.0.0.1:3000`

Default filtered Docker socket¶

The guided installer discovers the socket group and builds the proxy. For manual Compose commands, export the group in each new shell (or set its numeric value in the project’s local .env). From the repository root:

export DOCKER_SOCKET_GID=$(stat -c %g "${DOCKER_SOCKET_PATH:-/var/run/docker.sock}")
docker compose up -d --build --wait

Only the proxy mounts the host socket. The agent reaches it on a private network; the proxy publishes no host port. Observation permits version discovery, container listing, inspection, stats, events and image inspection by digest. Inspection can reveal environment variables and mounts. Keep the proxy network private.

To grant additional operations, export either variable and repeat the Compose command. Each value is a space-separated list of full container IDs. Get an ID with docker inspect -f '{{.Id}}' NAME. Update the list after a target is recreated. Unset the variable and reapply the command to revoke new requests.

Variable	Grants on the listed targets
`MONIT_PROXY_EXEC_TARGETS`	Filesystem probes and arbitrary non-privileged Docker execs, including commands as root inside the target
`MONIT_PROXY_LIFECYCLE_TARGETS`	Start, stop and restart

Choose trusted workload containers only. An exec into a privileged container or one with a host filesystem or Docker socket mount can grant host access. The allowlist limits the Docker API available to the agent; the proxy process itself holds the real socket. These settings grant transport access. Configure any monitoring rules or manual action credentials separately. The former docker-compose.socket-proxy.yml overlay is accepted for compatibility.

Migrate an existing agent¶

Keep your current checkout and Compose files until ready to switch. The guided installer stops before replacing an existing direct-socket agent. To migrate:

Back up the current Compose files, configuration and state. Keep your project name and named volume. List rules and filesystem probes that need Docker writes.
Set the socket GID and the required target IDs as described above. Keep these settings in the deployment environment for subsequent Compose invocations.
From the new checkout, use the same project name and UI/config overlays. Inspect docker compose config for inherited direct socket mounts or a custom DOCKER_HOST. Remove those overrides so only the proxy owns the socket.
Apply the reviewed configuration with docker compose up -d --build --wait and the chosen file list. Check /readyz, then verify any probes and actions against a disposable authorized target. To roll back, reapply the saved Compose files with the same project name and up -d --remove-orphans after checking which services will be removed. Keep the state volume.

Guided installation¶

On Linux amd64, install Git, Docker Engine, its Compose v2 plugin with up --wait support, and curl. For the web dashboard, install Python 3 and OpenSSL.

git clone --branch v1.3.3 --depth 1 https://github.com/decryptus/monit-docker.git
cd monit-docker
./install.sh

Press Enter to include the local dashboard. On first use, choose a username and a password of at least 12 characters. The script checks collection and the HTTPS login challenge, then prints the container count and address. The self-signed local certificate lasts seven days. Over SSH, run the displayed tunnel example on your workstation. Rerun ./install.sh --ui in the same directory to reuse credentials and the existing volume. Use ./install.sh --agent-only for the API alone. To remove an existing UI, follow the shutdown procedure below.

Prerequisites¶

Use Linux Docker Engine, a local Unix Docker socket and a current Docker Compose plugin with up --wait support. The account needs Docker access. The published agent/UI images target Linux amd64; other architectures need a separately tested build or emulation. Docker Desktop must use Linux containers; for Windows commands use WSL with Docker integration. The UI preparation also needs Python 3 and OpenSSL.

git clone https://github.com/decryptus/monit-docker.git
cd monit-docker
docker compose version
docker info

These commands use the default local socket. For rootless Docker or another local socket, set DOCKER_SOCKET_PATH to its absolute path. A missing path fails instead of creating a directory. Remote Docker contexts are outside this quickstart.

Start the agent¶

From the repository root:

docker compose config --quiet
docker compose up -d --wait --wait-timeout 180
curl -f http://127.0.0.1:9808/readyz
curl -f http://127.0.0.1:9808/v1/status

The agent observes containers every 30 seconds after each completed cycle. It does not restart workloads. /readyz returns 200 only after a successful fresh collection. /healthz only checks that HTTP responds. For diagnosis:

docker compose ps
docker compose logs --tail=100 monit-docker
docker compose exec monit-docker monit-docker stats --output json

Only the proxy receives the Docker socket. The agent API binds to host loopback.

Add the web UI¶

Prepare credentials once. Enter a username and a password of at least 12 characters; the password is not printed or passed as a process argument.

python3 examples/ui/prepare.py --self-signed
docker compose -f docker-compose.yml -f docker-compose.ui.yml config --quiet
docker compose -f docker-compose.yml -f docker-compose.ui.yml up -d --wait --wait-timeout 180

Open https://localhost:8443 and log in with those credentials. The generated certificate is for local development and expires in seven days. For this local example the browser reports it as untrusted. Use your trusted certificate for a real deployment, following the UI guide. The preparation command refuses to overwrite existing examples/ui/secrets.local; reuse those files on later runs.

The overlay reuses the existing UI service and its secret paths. It adds no Prometheus or Grafana, and enables no manual start/stop/restart controls. The loopback-only agent API remains available. Only the UI joins the frontend network. Do not combine the advanced examples/ui/compose.actions.yaml or journal overlay with the root files: follow their standalone instructions and relative paths instead.

Keep the same Compose file list for all UI lifecycle commands:

docker compose -f docker-compose.yml -f docker-compose.ui.yml ps
docker compose -f docker-compose.yml -f docker-compose.ui.yml logs --tail=100
docker compose -f docker-compose.yml -f docker-compose.ui.yml down

down preserves the named state volume and the credential files. Do not use --volumes when you need to preserve journals, restart budgets or other state. To return from the UI to agent-only, stop with both files, then start the base file.

Customize or update¶

Set MONIT_DOCKER_PORT or UI_PORT in the shell before running Compose to change host ports. The UI binds to loopback unless UI_BIND is explicitly changed. Changing a host port does not change internal agent addresses. Keep the same directory/project name so Compose reuses its named volume.

The examples pin agent and UI to 1.3.3. When updating versions, preserve your configuration and state, choose matching agent/UI versions, then pull and recreate the selected stack. docker compose pull alone does not change a running container.

docker compose -f docker-compose.yml -f docker-compose.ui.yml pull
docker compose -f docker-compose.yml -f docker-compose.ui.yml up -d --wait --wait-timeout 180

For agent-only use the same commands without -f arguments. See installation and upgrades for state compatibility.

Existing root cron installations¶

The previous root file used latest, mounted all of /var/run, and ran broad cron rules including PHP-FPM signals. The new root file intentionally starts an observation-only server. It does not execute the old MONIT_DOCKER_CRONS jobs.

Before pulling this change into an existing deployment, save its Compose file, configuration, state and audit files outside the checkout. Stop the old stack using that saved file and its original project name. Review each old rule and its container selection; follow the cron guide to retain scheduled jobs, including persistent state and an initial dry run. There is no automatic rule conversion. Then start the new entry point deliberately. Do not run both old and new action jobs over the same workloads without reviewing their coordination.

Try a reproducible incident¶

The memory tutorial adds a disposable worker, limits its memory, and then opts into one automatic restart after a sustained threshold. Use it for a local walkthrough before writing rules for your applications.

Add history later¶

Use the Prometheus/Grafana Compose guide when you need time-series history. That example is a separate stack, not another overlay on the root file. Stop the minimal stack first, or set distinct host ports. Email/Slack delivery requires the explicitly configured notification stack.