docs/getting-started/podman.md

Running Auralynq with Podman (production-shaped stack)

Auralynq is Podman-first — no Docker, no sudo required. This mode runs the full 7-service topology behind a TLS reverse proxy: caddy, web, api, worker, mcp, qdrant, phoenix.

For a lighter single-process setup with no containers, see no-podman.md instead.

Prerequisites

• Podman + a Podman Compose (podman compose or podman-compose)
• No Docker needed anywhere in this flow

make runtime-check   # verifies a Podman Compose command is available

1. Build and start

git clone https://github.com/MHHamdan/Auralynq.git && cd Auralynq
cp .env.example .env    # optional; only HUGGINGFACE_TOKEN matters for gated models

make images       # build versioned api/web/caddy images locally
make stack-up      # start the stack (alias: make up)

make stack-up starts caddy (public TLS) + web + api + mcp + worker + qdrant + phoenix, in a hardened order. Only the Caddy HTTPS port is meant to be public; everything else binds to loopback by default.

2. Seed and index data

podman exec auralynq-api auralynq data --sample
podman exec auralynq-api auralynq index --input /app/data/corpus

Or upload documents directly through the web UI's Ingest tab — no shell access needed.

3. Open it

• Web UI: https://localhost:8443 (accept the self-signed cert warning, or see server.md for a real domain / trusted cert)
• API docs: https://localhost:8443/api/docs
• Phoenix traces: loopback-only by default; SSH-tunnel to view, or expose intentionally if you understand the trade-off

Everyday commands

make stack-down     # stop
make stack-logs      # tail logs
make fresh           # wipe corpus + Qdrant volumes and start clean
make status          # container status (when using `make start`/`make stop`)

Rebuilding after a code change

podman-compose build can silently reuse cached layers for both the multi-stage web image and the single-stage API image. Always rebuild with podman build --no-cache directly, then fully cycle the stack (compose pins image IDs, so a plain restart won't pick up a new image):

make images
podman-compose -f compose.yml down && make stack-up

Where your data lives (Podman mode)

Corpus, vector index, and page cache live in named Podman volumes (not the host filesystem), so they survive stack-down/stack-up cycles but are separate from whatever ./data/ holds if you also ran no-Podman mode on the same machine. make fresh wipes exactly these volumes (auralynq-data, auralynq-qdrant) and nothing else.

Next steps

• Deploying to a remote server with a real domain/IP → server.md
• No containers at all → no-podman.md
• Something not working → troubleshooting.md