Installation

Choose a Python environment on the host or the official Docker image. Start by reading metrics.

Guided installation with Docker Compose

On Linux amd64, install Git, Docker Engine, Compose v2 and curl. The dashboard also needs Python 3 and OpenSSL. The following command checks out the installer for release 1.3.3.

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 dashboard. Choose your credentials, then open the local HTTPS address printed after the first collection. The self-signed certificate lasts seven days. On a remote server, use the SSH tunnel example. For the agent alone, use ./install.sh --agent-only. Running again in the same directory reuses your credentials and volume.

The installer discovers the socket group and stops before replacing an existing direct-socket agent. To preserve rules and state, follow the migration guide.

1. Prepare your machine

These examples assume Linux, a POSIX shell and a Docker Engine accessible by your account. Check docker ps -a. For Python, use Python 3.10 or 3.12 with venv and the system libmagic library (libmagic1 on Debian/Ubuntu). Stacks require Docker Compose v2 with up --wait.

Docker socket access grants powerful host privileges. A :ro mount does not make the Docker API read-only.

2A. Install with Python

python3 -m venv "$HOME/.local/share/monit-docker/venv"
"$HOME/.local/share/monit-docker/venv/bin/python" -m pip install 'monit-docker==1.3.3'
mkdir -p "$HOME/.local/state/monit-docker"
export PATH="$HOME/.local/share/monit-docker/venv/bin:$PATH"
export MONIT_DOCKER_LOGFILE="$HOME/.local/state/monit-docker/monit-docker.log"
export MONIT_DOCKER_RUNTIMEDIR="$HOME/.local/state/monit-docker/run"
monit-docker --help

These variables apply to the current shell. Keep these paths in your cron script or service definition. Installation uses the project’s declared dependencies, including HTTPdis and Sonicprobe.

3. Verify collection

Replace my-container with a name listed by Docker. Global options come before the subcommand.

docker ps -a
monit-docker stats --output json
monit-docker --name 'my-container' stats --rsc mem_usage --rsc cpu_percent

The JSON output should contain the selected containers and measurements. With no configuration file, the default local Docker connection can be used. See troubleshooting if collection fails.

2B. Use the Docker image

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  decryptus/monit-docker:1.3.3 \
  monit-docker stats --output json

The command after the image is explicit: monit-docker stats. Persistent rules also need a mounted state directory. The Docker serve guide provides a complete example.

4. Get the examples

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

This pinned checkout is used by the interface and monitoring guides. Next choose cron or serve.

See the 1.3.3 release notes for the compatibility contract, tested upgrades and validation limits.

5. Start with Docker Compose

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

From the versioned checkout above, this starts the agent in observation mode without automatic actions. To add the authenticated HTTPS UI or test the memory rule, follow the Compose guide. If you are replacing the old cron/PHP-FPM example, first read the Compose migration notes.

Only the proxy mounts the Docker socket in the root Compose stack. The agent can read container status and stats. Use MONIT_PROXY_EXEC_TARGETS for probes and exec commands and MONIT_PROXY_LIFECYCLE_TARGETS for start, stop or restart. Both lists take full container IDs. Refresh them after recreating a target.