From 6f37ddc92aa91ac18d857b2084196e293c0f55fa Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Mon, 29 Jun 2026 20:23:20 +0530 Subject: [PATCH 1/2] Self-hosting: rework Requirements page, add Requirements + Installation sidebar entries - Requirements-only pre-install checklist: hardware tiers, software (Docker 24.0+, Compose v2.20+, Git 2.0+) with per-OS install tabs, platform compatibility, and the network-ports reference. - Correct to current repo facts: AGENTCC_GATEWAY_PORT, 0.0.0.0 app-service binds, PeerDB ports only under COMPOSE_PROFILES=full. - Add Git as a prerequisite; fix the Windows WSL 2 memory guidance. - Sidebar: rename 'System requirements' -> 'Requirements' and add 'Installation'. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/lib/navigation.ts | 3 +- src/pages/docs/self-hosting/requirements.mdx | 71 ++++++++++---------- 2 files changed, 36 insertions(+), 38 deletions(-) diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 059c31d7..32731ba4 100644 --- a/src/lib/navigation.ts +++ b/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/install' }, { title: 'Environment variables', href: '/docs/self-hosting/environment' }, { title: 'Configuration', href: '/docs/self-hosting/configuration' }, { title: 'Docker Compose', href: '/docs/self-hosting/docker-compose' }, diff --git a/src/pages/docs/self-hosting/requirements.mdx b/src/pages/docs/self-hosting/requirements.mdx index 4e0ce3be..627cdf3e 100644 --- a/src/pages/docs/self-hosting/requirements.mdx +++ b/src/pages/docs/self-hosting/requirements.mdx @@ -1,24 +1,30 @@ --- -title: "Self-Hosting Requirements" -description: "Hardware sizing tiers, supported platforms, OS compatibility, and network port requirements before deploying Future AGI with Docker Compose." +title: "Self-hosting requirements" +description: "Hardware sizing tiers, supported platforms, OS compatibility, Docker versions, and the network ports each service uses. Everything you need to size and prepare a host before installing Future AGI." --- -## About +## Introduction -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), and a supported platform. Get these right and the [Install](/docs/self-hosting/install) run works on the first try. + + +Short on time? For a local trial you need **4 CPU cores, 8 GB RAM, 20 GB disk**, Docker Engine 24+, and Docker Compose v2.20+. Everything below is the detail behind those numbers. + ## 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. -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. ## Software @@ -27,70 +33,61 @@ Docker Desktop (Mac/Windows): Settings → Resources → set RAM ≥ 8 GB, disk |---|---|---| | Docker Engine | 24.0+ | `docker --version` | | Docker Compose | v2.20+ | `docker compose version` | +| Git | 2.0+ | `git --version` | ```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. +Or install [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/install/mac-install/) and allocate ≥ 8 GB RAM in **Settings → Resources**. ```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 ``` -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. With WSL 2, memory is set in WSL, not Docker's UI: add `memory=8GB` under a `[wsl2]` section in `%UserProfile%\.wslconfig`, then run `wsl --shutdown` to apply. The **Settings → Resources** sliders apply only to the Hyper-V backend. ## 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. + +## Network ports -All ports are configurable via `.env`. +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 | Exposed to | `.env` key | +| 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 - - - - Clone, configure, and run the full stack. - - - Set secrets and tune runtime flags before first boot. - - +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. From 76f4b8eaefc8b3a83e528b1fb704e925f704de1b Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Thu, 2 Jul 2026 13:30:14 +0530 Subject: [PATCH 2/2] docs(self-hosting): address Khushal review on Requirements (#696) - Title -> 'Requirements' (sync with sidebar); shorten description. - 'Introduction' -> 'In this page'; intro three-checks as bullets. - Note -> TLDR for the short-on-time summary. - Uniform OS tabs (consistent lead line); remove stranded macOS Docker Desktop line. - Update Install link + nav href for the install -> installation rename. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/lib/navigation.ts | 2 +- src/pages/docs/self-hosting/requirements.mdx | 25 +++++++++++++------- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 32731ba4..ca09232f 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -61,7 +61,7 @@ export const tabNavigation: NavTab[] = [ items: [ { title: 'Overview', href: '/docs/self-hosting' }, { title: 'Requirements', href: '/docs/self-hosting/requirements' }, - { title: 'Installation', href: '/docs/self-hosting/install' }, + { 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' }, diff --git a/src/pages/docs/self-hosting/requirements.mdx b/src/pages/docs/self-hosting/requirements.mdx index 627cdf3e..f23aa952 100644 --- a/src/pages/docs/self-hosting/requirements.mdx +++ b/src/pages/docs/self-hosting/requirements.mdx @@ -1,15 +1,21 @@ --- -title: "Self-hosting requirements" -description: "Hardware sizing tiers, supported platforms, OS compatibility, Docker versions, and the network ports each service uses. Everything you need to size and prepare a host before installing Future AGI." +title: "Requirements" +description: "System requirements and support for self-hosting Future AGI." --- -## Introduction +## In this page -Check three things before you install: a host that meets the sizing for your usage, the required software (Docker and Git), and a supported platform. Get these right and the [Install](/docs/self-hosting/install) run works on the first try. +Check three things before you install: - -Short on time? For a local trial you need **4 CPU cores, 8 GB RAM, 20 GB disk**, Docker Engine 24+, and Docker Compose v2.20+. Everything below is the detail behind those numbers. - +- 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. + + +For a local trial: **4 CPU cores, 8 GB RAM, 20 GB disk**, Docker Engine 24+, Docker Compose v2.20+, and Git. + ## Hardware tiers @@ -37,13 +43,14 @@ On Docker Desktop (Mac/Windows), raise the limits in **Settings → Resources**: +Install the tools with Homebrew, then start Colima: ```bash 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**. +Install the tools with apt, then enable the Docker daemon: ```bash sudo apt-get install -y docker.io docker-compose-v2 git sudo systemctl enable --now docker @@ -51,7 +58,7 @@ sudo usermod -aG docker $USER # log out and back in ``` -Install [Docker Desktop for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) with the WSL 2 backend. With WSL 2, memory is set in WSL, not Docker's UI: add `memory=8GB` under a `[wsl2]` section in `%UserProfile%\.wslconfig`, then run `wsl --shutdown` to apply. The **Settings → Resources** sliders apply only to the Hyper-V backend. +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.