From d3431e6f858ec0f762d3932fdc1c93e71bcc01a4 Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Mon, 29 Jun 2026 20:24:21 +0530 Subject: [PATCH 1/2] Self-hosting: add Installation page + sidebar entries - New Installation page for the current ./bin/install flow: Steps (clone + install, create first user via manage.py create_user, open the app), installer flags, Apple Silicon/arm64 note, manual install, verify-the-stack, everyday operations, and the dev/frontend run modes. - 'Deep dive' card to Environment variables (System configuration card omitted since that page is not in the base branch). - Replaces the old build-from-source v1.8.19_base draft with the published-image flow; every command verified against the live future-agi/future-agi repo. - 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/install.mdx | 128 ++++++++++++++++++++++++ 2 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 src/pages/docs/self-hosting/install.mdx 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/install.mdx b/src/pages/docs/self-hosting/install.mdx new file mode 100644 index 00000000..41f626f3 --- /dev/null +++ b/src/pages/docs/self-hosting/install.mdx @@ -0,0 +1,128 @@ +--- +title: "Install with Docker Compose" +description: "Bring up a self-hosted Future AGI instance with Docker Compose: clone the repo, run the installer, verify the stack, and create your first admin user." +--- + +## Introduction + +Docker Compose is the supported way to run a self-hosted Future AGI instance. Once you have the repo, `./bin/install` bootstraps your `.env`, brings up the stack from published images, waits for the backend health check, and prompts you to create the first user. First boot pulls images from Docker Hub and takes about a minute, with no source builds. Confirm your host meets the [requirements](/docs/self-hosting/requirements) first. + + +Short on time? Run `git clone https://github.com/future-agi/future-agi.git && cd future-agi && ./bin/install`, then open [http://localhost:3000](http://localhost:3000). Everything below is the detail behind that one command. + + +## Install + + + +```bash +git clone https://github.com/future-agi/future-agi.git +cd future-agi +./bin/install # Windows: bin\install.ps1 +``` + +The installer copies `.env.example` to `.env` if you do not have one, runs `docker compose up -d`, polls `http://localhost:8000/health/` until the backend is ready, then prompts you to create your first user. The stack boots fine against an empty `.env`, so you can take the defaults for a local trial. + +By default the installer brings up the standard stack (around 12 containers). Add `--full` to include the PeerDB CDC stack (around 22 containers) that populates the analytics views. + + + +The installer prompts you at the end. If you passed `--skip-user-creation`, create the account from the CLI instead: + +```bash +docker compose exec backend python manage.py create_user +``` + +You will be asked for an email, full name, and password. To script it, pass them inline: + +```bash +docker compose exec backend python manage.py create_user \ + --email you@example.com \ + --name "Your Name" \ + --password yourpassword +``` + + + +Log in at [http://localhost:3000](http://localhost:3000) with the user you just created. The backend API is at [http://localhost:8000](http://localhost:8000). + + + +### Installer flags + +| Flag | What it does | +|---|---| +| `--full` | Add the PeerDB CDC stack (around 22 containers) so the analytics views populate. | +| `--skip-user-creation` | Skip the first-user prompt. Create the account later with `create_user`. | +| `--no-up` | Bootstrap `.env` only. Do not start the stack. | +| `--wipe-volumes` | Remove stale project volumes before starting. This destroys existing data. | +| `--new-instance` | Start a fresh instance when existing volumes are detected. | + + +**Apple Silicon and arm64 hosts.** Prebuilt images are `linux/amd64`. On M-series Macs they run under Rosetta 2 (auto-enabled on Docker Desktop 4.16+), which is fine for evaluation with a 20 to 50 percent performance cost. For native arm64, build locally with `docker compose build` instead of pulling. On Linux arm64 such as Graviton, install `qemu-user-static`. + + +## Install without the script + +The installer is a convenience wrapper, not a requirement. To run the same steps by hand: + +```bash +cp .env.example .env # optional; an empty .env works for local +docker compose up -d +``` + +Then create the first user with the same `create_user` command shown above. + +## Verify the stack + +Check that every service is healthy before you log in. Under-provisioned RAM is the most common reason the backend never finishes booting, so confirm the [requirements](/docs/self-hosting/requirements) if it stalls. + +```bash +docker compose ps # every service should read "running" or "healthy" +docker compose logs -f backend # wait for "Application startup complete" +curl http://localhost:8000/health/ +``` + +When the backend logs `Application startup complete` and the health endpoint returns OK, the instance is ready. + +## Everyday operations + +A short reference for the commands you will use most: + +```bash +# Tail logs +docker compose logs -f backend worker + +# Shell into a container +docker compose exec backend bash +docker compose exec postgres psql -U futureagi -d futureagi + +# Stop the stack (data persists in named volumes) +./bin/uninstall # or: docker compose down + +# Wipe all data and start clean +./bin/uninstall --wipe-data # or: docker compose down -v + +# Remove everything: containers, volumes, .env, and built images +./bin/uninstall --purge +``` + +## Other ways to run it + +| Mode | Command | Use it for | +|---|---|---| +| Standard (default) | `docker compose up -d` | Local evaluation, team installs, and VM self-hosting. | +| Development | `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` | Contributing to Future AGI: hot reload, per-queue workers, host-accessible database ports, and the Temporal UI. | +| Frontend only | `docker compose -f docker-compose.frontend.yml up -d` | Pointing a local UI at a backend that runs elsewhere. | + + +For a frontend-only deploy, set `VITE_HOST_API` to the backend URL the browser can reach. It is applied when the container starts, so changing it needs only a restart of the frontend container, not a rebuild. + + +## Deep dive + + + + Set provider keys, secrets, and runtime flags in `.env`. + + From c19c52d38c438c1563df0c9fbe957f6e8ec04b6d Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Thu, 2 Jul 2026 13:33:14 +0530 Subject: [PATCH 2/2] docs(self-hosting): address Khushal review on Installation (#697) - Rename install.mdx -> installation.mdx (file = kebab of sidebar title); nav href updated. - Title -> 'Installation'; shorten description. - 'Introduction' -> 'In this page'; bullet the installer-does-this enumeration (de-duped Step 1). - Note -> TLDR. Footer 'Deep dive' -> 'Dive deeper'. - Drop trailing periods in the flags + modes tables and the card body. - Point the env card at the canonical nav path /docs/self-hosting/environment. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/lib/navigation.ts | 2 +- .../{install.mdx => installation.mdx} | 45 +++++++++++-------- 2 files changed, 27 insertions(+), 20 deletions(-) rename src/pages/docs/self-hosting/{install.mdx => installation.mdx} (70%) 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/install.mdx b/src/pages/docs/self-hosting/installation.mdx similarity index 70% rename from src/pages/docs/self-hosting/install.mdx rename to src/pages/docs/self-hosting/installation.mdx index 41f626f3..54d17e8f 100644 --- a/src/pages/docs/self-hosting/install.mdx +++ b/src/pages/docs/self-hosting/installation.mdx @@ -1,15 +1,22 @@ --- -title: "Install with Docker Compose" -description: "Bring up a self-hosted Future AGI instance with Docker Compose: clone the repo, run the installer, verify the stack, and create your first admin user." +title: "Installation" +description: "Install a self-hosted Future AGI instance with Docker Compose." --- -## Introduction +## In this page -Docker Compose is the supported way to run a self-hosted Future AGI instance. Once you have the repo, `./bin/install` bootstraps your `.env`, brings up the stack from published images, waits for the backend health check, and prompts you to create the first user. First boot pulls images from Docker Hub and takes about a minute, with no source builds. Confirm your host meets the [requirements](/docs/self-hosting/requirements) first. +Docker Compose is the supported way to run a self-hosted Future AGI instance. Confirm your host meets the [requirements](/docs/self-hosting/requirements) first, then `./bin/install` does the rest: - -Short on time? Run `git clone https://github.com/future-agi/future-agi.git && cd future-agi && ./bin/install`, then open [http://localhost:3000](http://localhost:3000). Everything below is the detail behind that one command. - +- Bootstraps your `.env` +- Brings up the stack from published images +- Waits for the backend health check +- Prompts you to create the first user + +First boot pulls images from Docker Hub and takes about a minute, with no source builds. + + +Run `git clone https://github.com/future-agi/future-agi.git && cd future-agi && ./bin/install`, then open [http://localhost:3000](http://localhost:3000). + ## Install @@ -21,7 +28,7 @@ cd future-agi ./bin/install # Windows: bin\install.ps1 ``` -The installer copies `.env.example` to `.env` if you do not have one, runs `docker compose up -d`, polls `http://localhost:8000/health/` until the backend is ready, then prompts you to create your first user. The stack boots fine against an empty `.env`, so you can take the defaults for a local trial. +The stack boots fine against an empty `.env`, so you can take the defaults for a local trial. By default the installer brings up the standard stack (around 12 containers). Add `--full` to include the PeerDB CDC stack (around 22 containers) that populates the analytics views. @@ -52,11 +59,11 @@ Log in at [http://localhost:3000](http://localhost:3000) with the user you just | Flag | What it does | |---|---| -| `--full` | Add the PeerDB CDC stack (around 22 containers) so the analytics views populate. | -| `--skip-user-creation` | Skip the first-user prompt. Create the account later with `create_user`. | -| `--no-up` | Bootstrap `.env` only. Do not start the stack. | -| `--wipe-volumes` | Remove stale project volumes before starting. This destroys existing data. | -| `--new-instance` | Start a fresh instance when existing volumes are detected. | +| `--full` | Add the PeerDB CDC stack (around 22 containers) so the analytics views populate | +| `--skip-user-creation` | Skip the first-user prompt; create the account later with `create_user` | +| `--no-up` | Bootstrap `.env` only, without starting the stack | +| `--wipe-volumes` | Remove stale project volumes before starting (destroys existing data) | +| `--new-instance` | Start a fresh instance when existing volumes are detected | **Apple Silicon and arm64 hosts.** Prebuilt images are `linux/amd64`. On M-series Macs they run under Rosetta 2 (auto-enabled on Docker Desktop 4.16+), which is fine for evaluation with a 20 to 50 percent performance cost. For native arm64, build locally with `docker compose build` instead of pulling. On Linux arm64 such as Graviton, install `qemu-user-static`. @@ -111,18 +118,18 @@ docker compose exec postgres psql -U futureagi -d futureagi | Mode | Command | Use it for | |---|---|---| -| Standard (default) | `docker compose up -d` | Local evaluation, team installs, and VM self-hosting. | -| Development | `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` | Contributing to Future AGI: hot reload, per-queue workers, host-accessible database ports, and the Temporal UI. | -| Frontend only | `docker compose -f docker-compose.frontend.yml up -d` | Pointing a local UI at a backend that runs elsewhere. | +| Standard (default) | `docker compose up -d` | Local evaluation, team installs, and VM self-hosting | +| Development | `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` | Contributing to Future AGI: hot reload, per-queue workers, host-accessible database ports, and the Temporal UI | +| Frontend only | `docker compose -f docker-compose.frontend.yml up -d` | Pointing a local UI at a backend that runs elsewhere | For a frontend-only deploy, set `VITE_HOST_API` to the backend URL the browser can reach. It is applied when the container starts, so changing it needs only a restart of the frontend container, not a rebuild. -## Deep dive +## Dive deeper - - Set provider keys, secrets, and runtime flags in `.env`. + + Set provider keys, secrets, and runtime flags in `.env`