docs(self-hosting): add Colima on macOS and make the Mac pages runtime-aware

[abhijaisrivastava15]

Summary

Adds /docs/self-hosting/colima, an end to end guide for running a self-hosted instance on macOS with Colima instead of Docker Desktop, and makes the three existing Mac-facing pages consistent with it.

Colima was already the runtime our own macOS install instructions told people to use, but it appeared in exactly one place: two commands in the macOS tab of Requirements. Every other Mac instruction in the section assumed Docker Desktop, including the tip directly above that tab, which opened with "Docker Desktop only" and then sent Mac readers to Settings → Resources, a screen Colima does not have.

Targets dev; promote to main after review.

The gap this closes

Three things about this stack break on Colima and none of them were written down. All three fail quietly, which is why they are worth a page:

1. The repo has to be cloned inside your home directory. Colima mounts only /Users/$USER into its VM, and it raises no error for a host path it cannot see: the bind mount simply arrives empty. The default stack mounts futureagi/.ci/clickhouse-storage-policy.xml into ClickHouse, so a clone in /opt or /Volumes gets Unknown storage policy 'tiered' and nothing points at the clone path as the cause.
2. Colima's default VM is 2 CPUs and 2 GiB of RAM. That OOM-kills ClickHouse or the backend part-way through boot, so you get a restart loop rather than an error. Same failure Docker Desktop users hit with its defaults, different place to fix it.
3. Development mode mounts the host Docker socket and defaults to /var/run/docker.sock, which is Docker Desktop's path. DOCKER_SOCKET is the override and was documented nowhere, not even in .env.example.

What changed

src/pages/docs/self-hosting/colima.mdx (new)

The guide. Install, VM sizing with a defaults-vs-needed table, the home directory mount trap with the list of host paths the stack actually bind mounts, Apple Silicon emulation (Rosetta vs QEMU, and why futureagi/future-agi is the one image that needs it), resizing after first start, the dev mode socket, and a Colima-specific troubleshooting table.

src/lib/navigation.ts

One nav entry, "Colima on macOS", between Requirements and Installation.

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

The tip said "Docker Desktop only" and gave Docker Desktop-only instructions, while the macOS tab immediately below it told you to install Colima. Rewritten to say what the limit is (the Docker VM's memory, too small by default on either runtime) and then where you set it per runtime. The macOS tab now names both runtimes, carries the --vm-type vz --vz-rosetta flags, and links to the new page.

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

The Apple Silicon note attributed Rosetta to "auto-enabled on Docker Desktop 4.16+", which is true and not the whole story: on Colima you get slower QEMU emulation unless the VM was created with --vm-type vz --vz-rosetta. Added that clause.

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

Cannot connect to the Docker daemon said to start Docker Desktop. It now also covers colima start and the case where the VM is up but docker context points elsewhere, which produces the identical error. ERROR: not enough free space said "Docker Desktop's virtual disk"; now runtime-neutral with the Colima command.

How every claim was grounded

No claim on the new page came from recall. What each one was read from:

Claim	Source
futureagi/future-agi is amd64 only, the other five default-stack images are multi-arch	docker manifest inspect on all seven first-party images
Colima defaults: 2 CPUs, 2 GiB, 100 GiB disk	colima start --help and the upstream README
Only $HOME is mounted, and an unmounted path fails silently	Colima's FAQ, quoted on the page, plus mount inside a live VM
An explicit --mount replaces the default home mount, and overlapping mounts are rejected	MountsOrDefault() in config/config.go and checkOverlappingMounts in environment/vm/lima/yaml.go
The four host paths the default stack bind mounts	docker-compose.yml on dev
DOCKER_SOCKET defaults to Docker Desktop's socket path	docker-compose.dev.yml on dev
Rosetta needs Colima 0.5.3+, macOS 13+, Apple Silicon, --vm-type vz	upstream README
amd64 images still run without Rosetta, just slower	binfmt_misc in a live VM shows both qemu-x86_64 and rosetta
127.0.0.1-bound published ports reach the host	ran a container on 127.0.0.1:18923 and curled it
The default stack has no build context for backend/worker	only one build: block in docker-compose.yml, and it is fi-collector

That last row is why the page does not tell arm64 users to run docker compose build backend worker: in the default stack that has nothing to build. The dev overlay does carry a build for backend, and the page points there instead.

Verification

scripts/audit-links.mjs, the same script pr-checks.yml runs, against this branch's tree:

  Link Audit
  ──────────────────────────────────────────────
  Pages found:         718
  Nav entries:         682
  Broken nav links:    0 ✓
  Broken content links:    0 ✓
  Orphan pages:        32 ⚠

Every internal link on the new page resolves, and the page is registered in nav rather than sitting in that orphan count. The 32 orphans are pre-existing and unrelated.

Review checklist

• No em-dashes anywhere in the five files
• Every MDX component used (TLDR, Note, Warning, Tip, Tabs, Tab, CardGroup, Card) already exists in src/components/docs/
• The --disk 64 number is consistent between Requirements and the new page
• The licensing rationale for choosing Colima is stated once, on the new page, not repeated in Requirements

The companion PR in future-agi/future-agi adds the same essentials to INSTALLATION.md and links here, so someone reading the repo rather than the docs site finds it.

[khushalsonawat]

Check comments

[khushalsonawat]

Shorten the description to only what's necessary, it's listing every sub-topic

[khushalsonawat]

organisation → organization, docs use American spelling

[khushalsonawat]

Only sizing and the clone path break first boot. Rosetta just makes it slow and the socket is dev mode only, so tone down "all four will bite you on the first boot"

[khushalsonawat]

Not the verbatim FAQ text, it drops "(e.g. using -v or --mount)". Restore it or don't set it as a quote

[khushalsonawat]

M-series, hyphenated, same as Installation

[khushalsonawat]

This passes under QEMU too, so it doesn't prove Rosetta. Say so or drop it

[khushalsonawat]

Comma splice, make it a colon

[khushalsonawat]

Installation has no dev mode section, link #other-ways-to-run-it instead

[khushalsonawat]

Two here, four on the Colima page. "Two more things differ" so the counts don't fight