Self-hosting: Installation 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/installation.mdx

@@ -0,0 +1,135 @@
+---
+title: "Installation"
+description: "Install a self-hosted Future AGI instance with Docker Compose."
+---
+
+## In this page
+
+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:
+
+- 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.
+
+<TLDR>
+Run `git clone https://github.com/future-agi/future-agi.git && cd future-agi && ./bin/install`, then open [http://localhost:3000](http://localhost:3000).
+</TLDR>
+
+## Install
+
+<Steps>
+<Step title="Clone the repository and run the installer">
+```bash
+git clone https://github.com/future-agi/future-agi.git
+cd future-agi
+./bin/install          # Windows: bin\install.ps1
+```
+
+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.
+</Step>
+
+<Step title="Create your first user">
+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
+```
+</Step>
+
+<Step title="Open the app">
+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).
+</Step>
+</Steps>
+
+### 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, 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 |
+
+<Note>
+**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`.
+</Note>
+
+## 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 |
+
+<Warning>
+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.
+</Warning>
+
+## Dive deeper
+
+<CardGroup cols={1}>
+  <Card title="Environment variables" icon="list-check" href="/docs/self-hosting/environment">
+    Set provider keys, secrets, and runtime flags in `.env`
+  </Card>
+</CardGroup>