Skip to main content

Quadlet Quickstart

This guide installs Alexandria EE onto a single Linux host using Podman Quadlet units (systemd-managed containers). This is the lower EE tier — see Deployment Shapes for what's excluded versus the Helm tier.

Prerequisites​

  • A Linux host with systemd ≥ 252 and Podman ≥ 4.4 (Quadlet ships with Podman 4.4)
  • An external Postgres instance reachable from the host (Cloud SQL, RDS, or a separate VM — Postgres is not bundled)
  • An Alexandria EE license key with a tier that includes the Quadlet SKU

1. Install Podman​

On RHEL/Fedora derivatives:

sudo dnf install -y podman

On Debian/Ubuntu:

sudo apt-get install -y podman

Verify:

podman --version       # ≥ 4.4
systemctl --version    # ≥ 252

2. Copy the Quadlet units​

The unit files live at dist/quadlet/*.container in this repo. Copy them into /etc/containers/systemd/:

sudo cp dist/quadlet/*.container /etc/containers/systemd/

3. Configure environment​

Each unit reads its configuration from /etc/alexandria/env. Create it:

sudo install -d -m 0750 /etc/alexandria
sudo tee /etc/alexandria/env >/dev/null <<EOF
LICENSE_KEY=<YOUR_LICENSE_KEY>
ALEXANDRIA_DB_URL=postgres://alex:CHANGE_ME@pg.internal:5432/alexandria?sslmode=require
ALEX_JWT_SECRET=$(openssl rand -hex 32)
ALEX_ADMIN_USERNAME=admin
ALEX_ADMIN_PASSWORD=<initial-password>
EOF
sudo chmod 0640 /etc/alexandria/env

4. Start the units​

Reload systemd to pick up the new generators, then start the API:

sudo systemctl daemon-reload
sudo systemctl enable --now alexandria-api.service
sudo systemctl enable --now alexandria-orchestrator.service
sudo systemctl enable --now alexandria-dashboard.service

Check status:

sudo systemctl status alexandria-api
sudo journalctl -u alexandria-api -f

5. Verify​

curl -fsS http://localhost:8080/health
curl -fsS http://localhost:8080/ready

# License check
curl -fsS http://localhost:8080/admin/license \
  -H "Authorization: Bearer <admin-token>" | jq .

What's excluded in Quadlet​

Endpoints that require Kubernetes primitives return 400 Bad Request or 501 Not Implemented with {"error": "kubernetes-required"}:

  • Managed LLM backends (Helm-provisioned pods)
  • Per-tenant Cilium NetworkPolicy
  • KEDA autoscaling
  • Pod log streaming

Features fully excluded from the build:

  • OIDC / SAML federation
  • SCIM provisioning
  • Multi-tenancy
  • WebAuthn / FIDO2
  • Vault KV v2 secrets backend
  • Memcached tool cache

If you need these, use the Helm Quickstart instead.

Next steps​