From 532bfd048a3c6ac9161b877dcbf099dc3a5676f7 Mon Sep 17 00:00:00 2001 From: chaib Date: Mon, 22 Jun 2026 20:29:15 +0000 Subject: [PATCH] wiki: update Deploy --- Deploy.md | 185 ++++++------------------------------------------------ 1 file changed, 18 insertions(+), 167 deletions(-) diff --git a/Deploy.md b/Deploy.md index 5bfd866..7d9d08f 100644 --- a/Deploy.md +++ b/Deploy.md @@ -1,181 +1,32 @@ # Deploy -This page walks through standing up **your own** Atlas OS instance: clone the repo, run the installer, point your domain at it, and let Caddy + Authentik gate every service. The end state is a browser desktop at `command./os/` with the full app catalog described in [[Atlas-OS]], all fronted by TLS and SSO. - -> **Sovereignty note:** the reference deployment runs on a single Hetzner VPS in the EU (NL/DE), so there is no US Cloud Act exposure. Any EU-based VPS with Docker works equally well. See [[Security]] for the full posture. - ---- +One-command installer for Atlas OS on a fresh Debian 12 / Ubuntu 24.04 server. ## Prerequisites -| Requirement | Detail | -|---|---| -| Host | A single Linux VPS with Docker + Docker Compose. The reference box runs ~55 containers / ~24 public services — size CPU/RAM/disk accordingly. | -| Domain | One domain you control, with the ability to add DNS records (wildcard recommended). | -| DNS | An `A`/`AAAA` record for the apex and a wildcard `*.` pointing at the VPS public IP. | -| Ports | `80` and `443` open to the world (Caddy handles ACME + TLS). Everything else stays private. | -| Admin identity | An email for the first Authentik admin account. The reference admin identity is `atlasshb` — pick your own. | -| Optional | A [Tailscale](https://tailscale.com) account if you want the private spine described in [[Fleet-and-Mesh]]. | +- Debian 12 or Ubuntu 24.04 (x86_64) +- Root access +- A domain with DNS pointed at the server +- A Tailscale account (free tier works) ---- - -## Deployment at a glance - -```mermaid -%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%% -flowchart TD - A[git clone the repo] --> B[deploy/install.sh] - B --> C[Bring your own domain
edit .env] - C --> D[Caddy brings up TLS
via ACME on 80/443] - D --> E[Authentik SSO
forward_auth gate] - E --> F[atlas-core.yml
compose stack up] - F --> G[Atlas OS desktop
command.your-domain/os/] -``` - ---- - -## 1. Clone the repo +## Install ```bash -git clone /atlas/atlas-os.git +git clone https://git.atlascorporation.nl/chaib/atlas-os cd atlas-os +chmod +x deploy/install.sh +sudo ./deploy/install.sh --domain yourdomain.com --email admin@yourdomain.com ``` -The repo ships its own docs — read `README.md` and the `docs/` directory before changing defaults. The git host itself (Forgejo) is one of the Ops apps in [[Atlas-OS]], so once you are live you can self-host the source too. +## Post-install ---- +1. Open `https://auth.yourdomain.com` and complete Authentik setup +2. Create your admin user in Authentik +3. Open `https://command.yourdomain.com/os/` — Atlas OS desktop boots +4. Add the AI stack: `docker compose -f deploy/compose/atlas-ai.yml up -d` +5. Configure `server/atlas_brain.py` with your mail accounts -## 2. Run the installer +## Secrets -The installer prepares the host (Docker checks, directory layout, secret scaffolding) and writes a starter environment file. - -```bash -./deploy/install.sh -``` - -`install.sh` will: - -1. Verify Docker / Compose are present. -2. Create the on-disk layout, including `/opt/atlas/secrets` (created `chmod 600`, never committed — see [[Security]]). -3. Generate a `.env` template for you to fill in (domain, admin email, secrets). -4. Pre-pull the base images referenced by `atlas-core.yml`. - -> Secrets live in two places only: the Vaultwarden vault (an Identity app in the catalog) and `/opt/atlas/secrets` on disk. `.gitignore` enforces that none of them enter git. - ---- - -## 3. Bring your own domain - -Atlas OS is domain-agnostic. Set your domain once, in `.env`, and every service inherits it as a subdomain. - -```bash -# .env -ATLAS_DOMAIN=your-domain.com -ATLAS_ADMIN_EMAIL=you@your-domain.com -``` - -Then add DNS records pointing at your VPS: - -| Record | Name | Value | -|---|---|---| -| `A` | `@` | `` | -| `A` | `*` | `` | - -The wildcard lets Caddy serve each app on its own hostname. Reference hostnames you will end up with: - -| Hostname | Service | -|---|---| -| `command./os/` | Atlas OS browser desktop ([[Atlas-OS]]) | -| `desktop.` | Webtop Remote Desktop ([[Remote-Desktop]]) | -| `atlasacademy.nl`-style site | Academy and your other [[Sites]] | - ---- - -## 4. Caddy + Authentik gate - -Caddy is the single public entry point. It terminates TLS (automatic ACME certificates on ports 80/443) and reverse-proxies to the internal containers. In front of protected apps it calls Authentik via `forward_auth` on the embedded outpost, so every request must carry a valid SSO session before it reaches the upstream. - -```mermaid -%%{init:{'theme':'base','themeVariables':{'primaryColor':'#0c1428','primaryTextColor':'#cfe2ff','primaryBorderColor':'#1F6FE0','lineColor':'#4EA0FF'}}}%% -flowchart LR - U[Browser] -->|HTTPS 443| C[Caddy
TLS termination] - C -->|forward_auth| AK[Authentik
embedded outpost] - AK -->|allow / deny| C - C -->|authenticated| S[Atlas OS apps
~24 public services] -``` - -What this gives you: - -- **TLS everywhere** — Caddy issues and renews certificates automatically. -- **One front door** — only `80`/`443` are public; container ports stay on the internal Docker network. -- **SSO on every app** — Authentik's `forward_auth` means a single login covers the whole desktop. The first admin you create during setup (reference: `atlasshb`) owns the directory. -- **Private-only services** — anything you do *not* want public is exposed over the Tailscale spine via `tailscale serve` instead of through Caddy. Details in [[Fleet-and-Mesh]]. - -After editing the Caddyfile, reload it: - -```bash -caddy reload --config /etc/caddy/Caddyfile -``` - ---- - -## 5. The `atlas-core.yml` compose stack - -`atlas-core.yml` is the heart of the deployment — the Compose file that brings up the core services (Caddy, Authentik, and the baseline app containers). Bring the stack up once your `.env` and DNS are in place: - -```bash -docker compose -f atlas-core.yml up -d -``` - -Useful operations: - -```bash -# Check what is running -docker compose -f atlas-core.yml ps - -# Tail logs for a single service -docker compose -f atlas-core.yml logs -f caddy - -# Pull updates and roll forward -git pull -docker compose -f atlas-core.yml pull -docker compose -f atlas-core.yml up -d -``` - -The full reference deployment runs ~55 containers and ~24 public services. `atlas-core.yml` defines the baseline; additional app modules layer on top of it. The complete catalog — Cockpit, Identity, AI, Work, Files & Comms, Ops, and Sites — is documented in [[Atlas-OS]], and the AI router / Brain layer in [[AI-Stack]]. - ---- - -## 6. First login & verification - -1. Browse to `https://command./os/`. -2. Caddy redirects you to Authentik for the first-run admin setup. Create your admin identity. -3. Land on the Atlas OS desktop. Confirm the app launcher loads. -4. Open **Uptime Kuma** (an Ops app) to confirm services report healthy. - -If a service 502s, check the Caddy logs first (`docker compose -f atlas-core.yml logs caddy`) and confirm DNS + the wildcard record have propagated. - ---- - -## Repo docs reference - -For anything beyond this overview, the repo is the source of truth: - -| File | Covers | -|---|---| -| `README.md` | Project overview and quick start | -| `deploy/install.sh` | The installer this page runs | -| `atlas-core.yml` | The core Compose stack | -| `docs/` | Per-service configuration and operations | -| `.env` (generated) | Your domain, admin email, and secret wiring | - ---- - -## Related pages - -- [[Atlas-OS]] — the desktop and the full 39-app catalog -- [[Architecture]] — how the single-VPS, Caddy-fronted design fits together -- [[Security]] — EU-sovereign hosting, MFA, secrets, backups -- [[Fleet-and-Mesh]] — Tailscale spine, NATS mesh, MeshCentral -- [[AI-Stack]] — kernel spine, Atlas Brain, LLM router -- [[Remote-Desktop]] — Webtop instance for browser-based dev +The installer generates strong secrets at `/opt/atlas/secrets/atlas.env` (chmod 600). +Never commit this file. It is in `.gitignore`.