Installation

Prerequisites

Rust 1.85+
Docker (recommended for local Postgres/Redis)
Optional: pg_dump and pg_restore for backup/restore workflows

1. Clone and Build

git clone https://github.com/<your-org>/athena.git
cd athena
cargo build --release

2. Configure Environment

Create .env with at least the logging client URI:

POSTGRES_ATHENA_LOGGING_URI=postgres://athena:athena@localhost:5433/athena_logging

If your environment provides non-Linux paths for Postgres tools, override:

ATHENA_PG_DUMP_PATH=/usr/bin/pg_dump
ATHENA_PG_RESTORE_PATH=/usr/bin/pg_restore

3. Start Local Dependencies

docker compose up -d postgres

4. Run Athena API

cargo run --

Default API port is 4052.

cargo run -- --api-only still works, but it is now a deprecated alias for the same boot path.

Optional: Split worker ownership into separate processes

Athena still defaults to one main binary. Split worker binaries are optional and all of them read the same config.yaml and .env.

Full API + daemon split

Set daemon.enabled: true in config.yaml, then run:

# terminal 1
cargo run --

# terminal 2
cargo run -p athena-daemon --bin athena_daemon

In this profile, athena_daemon owns clone execution plus deferred, backup, Typesense, and optional legacy workers.

Clone-only hybrid split

If clone jobs need a separate supervisor first, keep daemon.enabled: false and run:

# terminal 1
cargo run --

# terminal 2
cargo run -p athena-daemon --bin athena_clone_worker

This is the only supported partial split today. Backup, deferred, Typesense, and legacy workers do not yet have a per-family "external only, inline off" toggle.

5. Verify Health

curl http://localhost:4052/ping
curl http://localhost:4052/health/cluster

If clone execution matters in your environment, also verify that either athena_daemon or athena_clone_worker is running before expecting /admin/provision/clones* jobs to leave the queued state.

Optional: Run Web Explorer

The apps/web Next.js app can be started against your local Athena instance:

cd apps/web
pnpm install
NEXT_PUBLIC_ATHENA_BASE_URL=http://localhost:4052 \
NEXT_PUBLIC_ATHENA_CLIENT=athena_logging \
pnpm dev

Installation

On this page