wiki: update Deploy
chaib
parent
159058d041
commit
532bfd048a
1 changed files with 18 additions and 167 deletions
185
Deploy.md
185
Deploy.md
|
|
@ -1,181 +1,32 @@
|
||||||
# Deploy
|
# 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.<your-domain>/os/` with the full app catalog described in [[Atlas-OS]], all fronted by TLS and SSO.
|
One-command installer for Atlas OS on a fresh Debian 12 / Ubuntu 24.04 server.
|
||||||
|
|
||||||
> **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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
| Requirement | Detail |
|
- Debian 12 or Ubuntu 24.04 (x86_64)
|
||||||
|---|---|
|
- Root access
|
||||||
| Host | A single Linux VPS with Docker + Docker Compose. The reference box runs ~55 containers / ~24 public services — size CPU/RAM/disk accordingly. |
|
- A domain with DNS pointed at the server
|
||||||
| Domain | One domain you control, with the ability to add DNS records (wildcard recommended). |
|
- A Tailscale account (free tier works)
|
||||||
| DNS | An `A`/`AAAA` record for the apex and a wildcard `*.<your-domain>` 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]]. |
|
|
||||||
|
|
||||||
---
|
## Install
|
||||||
|
|
||||||
## 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<br/>edit .env]
|
|
||||||
C --> D[Caddy brings up TLS<br/>via ACME on 80/443]
|
|
||||||
D --> E[Authentik SSO<br/>forward_auth gate]
|
|
||||||
E --> F[atlas-core.yml<br/>compose stack up]
|
|
||||||
F --> G[Atlas OS desktop<br/>command.your-domain/os/]
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Clone the repo
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone <your-forgejo-url>/atlas/atlas-os.git
|
git clone https://git.atlascorporation.nl/chaib/atlas-os
|
||||||
cd 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.
|
The installer generates strong secrets at `/opt/atlas/secrets/atlas.env` (chmod 600).
|
||||||
|
Never commit this file. It is in `.gitignore`.
|
||||||
```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` | `@` | `<vps-ip>` |
|
|
||||||
| `A` | `*` | `<vps-ip>` |
|
|
||||||
|
|
||||||
The wildcard lets Caddy serve each app on its own hostname. Reference hostnames you will end up with:
|
|
||||||
|
|
||||||
| Hostname | Service |
|
|
||||||
|---|---|
|
|
||||||
| `command.<your-domain>/os/` | Atlas OS browser desktop ([[Atlas-OS]]) |
|
|
||||||
| `desktop.<your-domain>` | 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<br/>TLS termination]
|
|
||||||
C -->|forward_auth| AK[Authentik<br/>embedded outpost]
|
|
||||||
AK -->|allow / deny| C
|
|
||||||
C -->|authenticated| S[Atlas OS apps<br/>~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.<your-domain>/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
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue