docker-ara

Slim, production-ready container image for ARA Records Ansible 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)

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 for a ready-to-use stack with MariaDB.

# 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

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

pip install ara

Then add to ansible.cfg:

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

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