# Docker

**English** · [Português](pt-BR/docker.md)

Acauã is distributed as an official container image:
`git.lucasrguerra.dev.br/ciberfauna/acaua`.

Available image tags:
- `latest`: Most recent stable release.
- `X.Y.Z` / `X.Y`: Pinned semantic versions.
- `edge`: Built automatically from the `main` branch.

The container runs as an unprivileged system user (`acaua`, UID 10001), with a
read-only root filesystem (`read_only: true`), all capabilities dropped
(`cap_drop: [ALL]`), and security hardening (`no-new-privileges:true`).

## Compose deployment

The recommended production and lab deployment uses Docker Compose:

```bash
cp .env.example .env   # configure ZEEK_INTERFACE (authorized networks only)
docker compose pull && docker compose up -d
```

To build and run locally from source:

```bash
docker compose up -d --build
```

The stack coordinates two services:

| Service | Image | Purpose | Security profile |
|---|---|---|---|
| `zeek` | `zeek/zeek:9.0.1` | Network packet capture and hourly log rotation | Host network, `NET_RAW` and `NET_ADMIN` capabilities |
| `acaua` | `git.lucasrguerra.dev.br/ciberfauna/acaua` | Analytical processing, API and web dashboard | Unprivileged (UID 10001), read-only rootfs, no capabilities |

## Volumes and data layout

The stack uses named volumes to manage ownership and permissions cleanly:

- `zeek-logs`: Shared volume mounted at `/logs` in the Zeek service and mounted
  **read-only** at `/data/zeek:ro` in the Acauã service.
- `acaua-data`: Dedicated read-write volume mounted at `/data/acaua` for DuckDB
  analytical store, Parquet partitions and runtime files.

To inspect or extract data on the host:

```bash
docker compose cp acaua:/data/acaua ./local-acaua-backup
```

Or run a one-off inspection container:

```bash
docker run --rm -v acaua_acaua-data:/data:ro debian:trixie-slim ls -la /data
```

## Updating

Because Acauã runs as a multi-user collective SOC daemon, updates are performed
by pulling the latest verified image:

```bash
docker compose pull && docker compose up -d
```

The running daemon shuts down cleanly on `SIGTERM` within sub-second intervals,
ensuring Parquet writes and DuckDB transactions are committed properly.

## Security notes

- The `zeek` service requires packet capture privileges (`NET_RAW`, `NET_ADMIN`).
  Run it only on interfaces and networks you are explicitly authorized to monitor.
- The default dashboard binding is loopback-only (`ACAUA_PUBLISH=127.0.0.1:8787`).
  Do not expose the service on external interfaces without an authenticating reverse proxy.
- The image contains no telemetry. Outbound traffic is restricted to operator-initiated
  update checks against the Gitea Releases API.