Docker Compose

The Compose file runs kogut on port 8484 with a data volume. For HTTPS, use the Caddy or Tailscale variant.

Start kogut

1. Download the Compose file:

   curl -fsSLO https://raw.githubusercontent.com/piotrkowski/kogut/main/deploy/docker/compose.yml

2. Set KOGUT_URL in compose.yml to the exact URL you open, such as http://localhost:8484. The file publishes plain HTTP.

3. Start kogut:

   docker compose up -d

4. Open that URL and create your account with the setup token from the log:

   docker compose logs kogut | grep setup_token

Add a configuration file

Create ./config/kogut.toml and add to kogut’s entries in compose.yml:

environment:
  - KOGUT_CONFIG=/etc/kogut/kogut.toml
  - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
volumes:
  - ./config:/etc/kogut:ro

Put TELEGRAM_BOT_TOKEN=... in .env, keep that file out of git, and write the secret as ${TELEGRAM_BOT_TOKEN} in kogut.toml.

Monitor the same host

With KOGUT_LOCAL_AGENT=1, kogut runs the agent inside the server and adds its own host, with no host token and no second container.

1. Download this variant and use it instead of compose.yml:

   curl -fsSLO https://raw.githubusercontent.com/piotrkowski/kogut/main/deploy/docker/local-agent.compose.yml

2. Set KOGUT_URL as in compose.yml. The variant uses host networking, so kogut listens on port 8484 of the host, and pid: host with the host root mounted read-only at /host.

3. For container metrics, put DOCKER_GID=<group id> in .env, from stat -c %g /var/run/docker.sock. Without them, remove group_add and the socket mount.

4. Start kogut:

   docker compose -f local-agent.compose.yml up -d

The host appears under Hosts with the name from its /etc/hostname, or joins the host of that name from kogut.toml. kogut gives it a new token at every start and keeps it only in memory. If the host already reports through another agent, that agent’s token stops working and kogut logs a warning. Unsent agent data waits in /data/agent.

With a separate agent container

To keep the server off the host’s network and processes:

1. Create a host token under Hosts → Add a server.

2. Download the agent service:

   curl -fsSLO https://raw.githubusercontent.com/piotrkowski/kogut/main/deploy/docker/agent.compose.yml

3. In agent.compose.yml, set KOGUT_SERVER=http://127.0.0.1:8484 and replace KOGUT_TOKEN with the host token. Loopback permits plain HTTP.

4. Put DOCKER_GID=<group id> in .env, from stat -c %g /var/run/docker.sock. Keep .env and the agent file with its token out of git.

5. Start both services:

   docker compose -f compose.yml -f agent.compose.yml up -d

Read Permissions and the Docker socket before mounting the socket, and Agent in Docker for the container’s limits.

If this host fails, kogut cannot alert about it. Use a separate monitoring server or kogut edge.

Update

Follow Upgrading with the same Compose files. For the server alone:

docker compose pull
docker compose up -d