Self-hosting: Requirements page

src/lib/navigation.ts

@@ -60,7 +60,8 @@ export const tabNavigation: NavTab[] = [
             title: 'Self-Hosting',
             items: [
               { title: 'Overview', href: '/docs/self-hosting' },
-              { title: 'System requirements', href: '/docs/self-hosting/requirements' },
+              { title: 'Requirements', href: '/docs/self-hosting/requirements' },
+              { title: 'Installation', href: '/docs/self-hosting/installation' },
               { title: 'Environment variables', href: '/docs/self-hosting/environment' },
               { title: 'Configuration', href: '/docs/self-hosting/configuration' },
               { title: 'Docker Compose', href: '/docs/self-hosting/docker-compose' },

src/pages/docs/self-hosting/requirements.mdx

@@ -1,24 +1,36 @@
 ---
-title: "Self-Hosting Requirements"
-description: "Hardware sizing tiers, supported platforms, OS compatibility, and network port requirements before deploying Future AGI with Docker Compose."
+title: "Requirements"
+description: "System requirements and support for self-hosting Future AGI."
 ---
 
-## About
+## In this page
 
-Hardware tiers, supported platforms, and the network ports each service uses. Read this first to size your environment before running [Docker Compose](/docs/self-hosting/docker-compose).
+Check three things before you install:
+
+- A host that meets the sizing for your usage
+- The required software: Docker and Git
+- A supported platform
+
+Get these right and the [Installation](/docs/self-hosting/installation) run works on the first try.
+
+<TLDR>
+For a local trial: **4 CPU cores, 8 GB RAM, 20 GB disk**, Docker Engine 24+, Docker Compose v2.20+, and Git.
+</TLDR>
 
 ## Hardware tiers
 
+Pick the row that matches how you'll use the instance. The stack runs on the Evaluation tier, but ClickHouse and the Temporal worker are the resource drivers. Under-provisioning RAM is the most common cause of a failed first boot.
+
 | Tier | Use case | CPU | RAM | Disk |
 |---|---|---|---|---|
 | **Evaluation** | Local trial, single user | 4 cores | 8 GB | 20 GB |
-| **Team** | 1–20 users, regular eval runs | 8 cores | 16 GB | 50 GB |
+| **Team** | 1-20 users, regular eval runs | 8 cores | 16 GB | 50 GB |
 | **Production** | 20+ users, high throughput | 16+ cores | 32+ GB | 200 GB+ SSD |
 
-Resource drivers: ClickHouse and Temporal worker each hold ~1 GB RAM at steady state. First image build is ~6 GB disk. ClickHouse grows with trace volume; Postgres stays small.
+ClickHouse and the Temporal worker each hold ~1 GB RAM at steady state. ClickHouse grows with trace volume over time; Postgres stays small. Pulling the images takes a few GB of disk on the first run.
 
 <Tip>
-Docker Desktop (Mac/Windows): Settings → Resources → set RAM ≥ 8 GB, disk ≥ 64 GB. The defaults (2–4 GB RAM) will OOM-kill ClickHouse or the backend.
+On Docker Desktop (Mac/Windows), raise the limits in **Settings → Resources**: RAM ≥ 8 GB, disk ≥ 64 GB. The defaults (2-4 GB RAM) will OOM-kill ClickHouse or the backend before the stack finishes booting.
 </Tip>
 
 ## Software
@@ -27,70 +39,62 @@
 |---|---|---|
 | Docker Engine | 24.0+ | `docker --version` |
 | Docker Compose | v2.20+ | `docker compose version` |
+| Git | 2.0+ | `git --version` |
 
 <Tabs>
 <Tab title="macOS">
+Install the tools with Homebrew, then start Colima:
 ```bash
-brew install docker docker-compose colima
+brew install docker docker-compose colima git
 colima start --cpu 4 --memory 8 --disk 64
 ```
-Or install [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/install/mac-install/) and allocate ≥ 8 GB RAM in Settings → Resources.
 </Tab>
 <Tab title="Linux">
+Install the tools with apt, then enable the Docker daemon:
 ```bash
-sudo apt-get install -y docker.io docker-compose-v2
+sudo apt-get install -y docker.io docker-compose-v2 git
 sudo systemctl enable --now docker
 sudo usermod -aG docker $USER   # log out and back in
 ```
 </Tab>
 <Tab title="Windows">
-Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) with WSL 2 backend. Allocate ≥ 8 GB RAM in Settings → Resources.
+Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) with the WSL 2 backend, then set the memory limit in WSL, not Docker's UI: add `memory=8GB` under a `[wsl2]` section in `%UserProfile%\.wslconfig` and run `wsl --shutdown` to apply. The **Settings → Resources** sliders apply only to the Hyper-V backend.
 </Tab>
 </Tabs>
 
 ## Platform compatibility
 
-The `code-executor` service requires `privileged: true`. Platforms that block it will crash the service; the rest of the stack still runs.
+Future AGI runs on any host that allows **privileged containers**. The `code-executor` service needs `privileged: true` to sandbox the user code it runs for evaluations, so platforms that block privileged mode lose that one service: the rest of the stack still runs, but code-based eval features are unavailable.
 
 | Platform | Supported | Notes |
 |---|---|---|
 | Linux bare metal / EC2 / GCE / Azure VM | Yes | Full support |
-| GKE / EKS with privileged enabled | Yes | Requires PodSecurityPolicy exception |
+| GKE / EKS with privileged enabled | Yes | Requires a PodSecurityPolicy exception |
 | ECS Fargate | No | `privileged: true` not supported |
 | Google Cloud Run | No | Same |
 | Render / Railway / Fly.io | No | Managed platforms block privileged mode |
 
-## Ports reference
+Helm/Kubernetes and air-gapped install are on the roadmap. Docker Compose is the supported path today.
 
-All ports are configurable via `.env`.
+## Network ports
 
-| Service | Default | Exposed to | `.env` key |
+Make sure these host ports are free before you install, or remap any that collide. Every published port reads from `.env` with a built-in default (for example `${FRONTEND_PORT:-3000}`), so you can change one without touching the Compose file.
+
+| Service | Default | Bind | `.env` key |
 |---|---|---|---|
 | Frontend | `3000` | `0.0.0.0` | `FRONTEND_PORT` |
 | Backend API | `8000` | `0.0.0.0` | `BACKEND_PORT` |
-| Gateway | `8090` | Internal only | `GATEWAY_PORT` |
-| Model serving | `8080` | Internal only | `SERVING_PORT` |
-| Code executor | `8060` | Internal only | `CODE_EXECUTOR_PORT` |
-| Postgres | `5432` | `127.0.0.1` (dev: public) | `PG_PORT` |
-| ClickHouse HTTP | `8123` | `127.0.0.1` (dev: public) | `CH_HTTP_PORT` |
-| ClickHouse TCP | `9000` | `127.0.0.1` (dev: public) | `CH_PORT` |
-| Redis | `6379` | `127.0.0.1` (dev: public) | `REDIS_PORT` |
+| Gateway | `8090` | `0.0.0.0` | `AGENTCC_GATEWAY_PORT` |
+| Model serving | `8080` | `0.0.0.0` | `SERVING_PORT` |
+| Code executor | `8060` | `0.0.0.0` | `CODE_EXECUTOR_PORT` |
+| Postgres | `5432` | `127.0.0.1` | `PG_PORT` |
+| ClickHouse HTTP | `8123` | `127.0.0.1` | `CH_HTTP_PORT` |
+| ClickHouse TCP | `9000` | `127.0.0.1` | `CH_PORT` |
+| Redis | `6379` | `127.0.0.1` | `REDIS_PORT` |
 | MinIO API | `9005` | `127.0.0.1` | `MINIO_API_PORT` |
 | MinIO console | `9006` | `127.0.0.1` | `MINIO_CONSOLE_PORT` |
-| Temporal | `7233` | `127.0.0.1` (dev: public) | `TEMPORAL_PORT` |
-| Temporal UI | `8085` | Dev mode only | `TEMPORAL_UI_PORT` |
+| Temporal | `7233` | `127.0.0.1` | `TEMPORAL_PORT` |
 | PeerDB server | `9900` | `127.0.0.1` | `PEERDB_PORT` |
 | PeerDB UI | `3001` | `0.0.0.0` | `PEERDB_UI_PORT` |
 
-In production, only the frontend and backend ports should be internet-facing, and only behind a TLS-terminating reverse proxy.
-
-## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Docker Compose" icon="docker" href="/docs/self-hosting/docker-compose">
-    Clone, configure, and run the full stack.
-  </Card>
-  <Card title="Environment Variables" icon="settings" href="/docs/self-hosting/environment">
-    Set secrets and tune runtime flags before first boot.
-  </Card>
-</CardGroup>
+The data stores (Postgres, ClickHouse, Redis, MinIO, Temporal) bind to `127.0.0.1`; the application services bind to `0.0.0.0`. PeerDB server and UI only run when you enable the CDC stack with `COMPOSE_PROFILES=full`, so those two ports are only in use in that mode.