Chaib Aarab a90a428189 docs: comprehensive README with Mermaid architecture diagram

- Full service map (18 public services documented)
- Mermaid architecture diagram: Internet → Caddy → Authentik → Apps → AI
- AI stack diagram: local router tiers + cloud fallback chain
- Deployment guide: VPS spec, Caddy SSO pattern, env layout
- Security model: perimeter, auth gates, AI kill-switch, secrets policy
- Repo structure tree
- Atlas branding header + shields.io badges

2026-06-22 20:16:12 +02:00

1.7 KiB

Raw Blame History

Deployment guide

Stack overview

All services run as Docker containers on a single VPS, fronted by Caddy. Authentik provides SSO with forward_auth — no per-service login required.

Minimum VPS spec

Resource	Minimum	Recommended
CPU	4 vCPU	8 vCPU
RAM	8 GB	16 GB
Disk	80 GB SSD	160 GB SSD
OS	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS

Directory layout on the VPS

/opt/atlas/
├── atlas-desktop/       # Atlas OS static files
├── brain/               # The Mind: brain.py, state files
├── cockpit/             # Cockpit API (Python FastAPI)
├── evolution/           # WhatsApp bridge config
├── forgejo/             # Forgejo docker-compose
├── nextcloud/           # Nextcloud docker-compose
└── secrets/             # NOT in git — env files, keys

Caddy + Authentik SSO pattern

Every service uses the same forward_auth block:

service.yourdomain.com {
    forward_auth authentik-server:9000 {
        uri /outpost.goauthentik.io/auth/caddy
        copy_headers X-Authentik-Username X-Authentik-Name X-Authentik-Email
    }
    reverse_proxy localhost:PORT
}

Starting order

Authentik (identity must be up first)
Caddy (depends on Authentik for forward_auth)
All other services (order-independent)
Atlas Brain / cockpit (depends on Odoo + Evolution)

Environment variables

Create /opt/atlas/secrets/ (not in git) with:

brain.env — ANTHROPIC_API_KEY, LLM router URLs
odoo.env — DB credentials
nextcloud.env — DB credentials, admin password
evolution.env — WhatsApp API key
router-secrets.env — GROQ_API_KEY, CEREBRAS_API_KEY, OPENROUTER_API_KEY

1.7 KiB Raw Blame History