docker-ara/README.md

# docker-ara

Slim, production-ready container image for [ARA Records Ansible](https://ara.readthedocs.io/en/latest/) built on **AlmaLinux 9 minimal**.

Features:
- Minimal image footprint (`almalinux:9.5-minimal` base, build tools removed after install)
- **tini** as PID 1 — correct signal handling and zombie reaping for crond child processes
- Supports **SQLite** (default), **MariaDB/MySQL**, and **PostgreSQL** via environment variables
- Built-in **crond** — automatically prunes playbooks older than a configurable number of days
- All settings configurable at runtime through environment variables

---

## Quick start (SQLite)

```bash
docker build -f docker/Dockerfile -t ara .

docker run -d \
  --name ara \
  -p 8000:8000 \
  -v ara_data:/opt/ara \
  ara
```

Then open <http://localhost:8000>.

---

## Environment variables

All ARA server settings map directly to environment variables.  
Full reference: <https://ara.readthedocs.io/en/latest/api-configuration.html>

### Core

| Variable | Default | Description |
|---|---|---|
| `ARA_BASE_DIR` | `/opt/ara` | Data & config directory |
| `ARA_SECRET_KEY` | *(random)* | Django secret key — **set a stable value in production** |
| `ARA_ALLOWED_HOSTS` | `["127.0.0.1","localhost","::1"]` | Hosts the server will respond to |
| `TZ` | `UTC` | System timezone — controls **when crond fires** |
| `ARA_TIME_ZONE` | same as `TZ` | Timezone for ARA to store/display results — keep in sync with `TZ` |
| `ARA_LOG_LEVEL` | `INFO` | Log verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |

### Database

| Variable | Default | Description |
|---|---|---|
| `ARA_DATABASE_ENGINE` | `django.db.backends.sqlite3` | `sqlite3`, `mysql`, or `postgresql` |
| `ARA_DATABASE_NAME` | `~/.ara/server/ansible.sqlite` | DB name (or path for SQLite) |
| `ARA_DATABASE_HOST` | *(none)* | Database host |
| `ARA_DATABASE_PORT` | *(none)* | Database port |
| `ARA_DATABASE_USER` | *(none)* | Database user |
| `ARA_DATABASE_PASSWORD` | *(none)* | Database password |
| `ARA_DATABASE_CONN_MAX_AGE` | `0` | Persistent connection lifetime (seconds) |

### Security / authentication

| Variable | Default | Description |
|---|---|---|
| `ARA_READ_LOGIN_REQUIRED` | `false` | Require auth for read requests |
| `ARA_WRITE_LOGIN_REQUIRED` | `false` | Require auth for write requests |

### Server tuning

| Variable | Default | Description |
|---|---|---|
| `ARA_PORT` | `8000` | Port gunicorn listens on |
| `ARA_GUNICORN_WORKERS` | `4` | Number of gunicorn worker processes |
| `ARA_PAGE_SIZE` | `100` | Results per page from the API |

### Maintenance / pruning

| Variable | Default | Description |
|---|---|---|
| `ARA_PRUNE_DAYS` | `30` | Delete playbooks older than this many days |
| `ARA_PRUNE_CRON` | `0 2 * * *` | Cron schedule for pruning (daily at 02:00) |

The prune job uses `ara playbook prune --client offline` so it accesses the database directly without going through the HTTP server. Output is forwarded to `docker logs`.

---

## Docker Compose — MariaDB

See [`docker-compose.yml`](docker-compose.yml) for a ready-to-use stack with MariaDB.

```bash
# Copy and edit the environment file
cp .env.example .env

# Start the stack
docker compose up -d

# View logs
docker compose logs -f ara
```

---

## Manual pruning

```bash
# Preview what would be deleted (no --confirm = dry run)
docker exec ara ara playbook prune --client offline --days 30

# Actually delete
docker exec ara ara playbook prune --client offline --days 30 --confirm
```

---

## Configuring Ansible to report to ARA

Install the ARA callback plugin on your Ansible controller:

```bash
pip install ara
```

Then add to `ansible.cfg`:

```ini
[defaults]
callback_plugins = $(python3 -m ara.setup.callback_plugins)

[ara]
api_client = http
api_server = http://<ara-host>:8000
```