Spaces:
Paused
Paused
| # 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](no-podman.md) instead. | |
| ## Prerequisites | |
| - Podman + a Podman Compose (`podman compose` or `podman-compose`) | |
| - No Docker needed anywhere in this flow | |
| ```bash | |
| make runtime-check # verifies a Podman Compose command is available | |
| ``` | |
| ## 1. Build and start | |
| ```bash | |
| 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 | |
| ```bash | |
| 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](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 | |
| ```bash | |
| 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): | |
| ```bash | |
| 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](server.md) | |
| - No containers at all → [no-podman.md](no-podman.md) | |
| - Something not working → [troubleshooting.md](troubleshooting.md) | |