# Docker Compose

Run kogut and an optional host agent with Docker Compose.

The Compose file runs kogut on port 8484 with a data volume. For HTTPS, use the
[Caddy](https://docs.kogut.dev/installation/caddy/) or [Tailscale](https://docs.kogut.dev/installation/tailscale/) variant.

## Start kogut

1. Download the Compose file:

   ```sh
   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:

   ```sh
   docker compose up -d
   ```

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

   ```sh
   docker compose logs kogut | grep setup_token
   ```

## Add a configuration file

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

```yaml title="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`](https://docs.kogut.dev/reference/configuration/).

## 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`:

   ```sh
   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:

   ```sh
   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:

   ```sh
   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:

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

Read [Permissions and the Docker socket](https://docs.kogut.dev/agent/permissions/) before mounting the
socket, and [Agent in Docker](https://docs.kogut.dev/agent/docker/) for the container's limits.

If this host fails, kogut cannot alert about it. Use a separate monitoring server or
[kogut edge](https://docs.kogut.dev/high-availability/kogut-edge/).

## Update

Follow [Upgrading](https://docs.kogut.dev/installation/upgrading/) with the same Compose files. For the server alone:

```sh
docker compose pull
docker compose up -d
```