Installation

Deploy and configure your ClearFox portal.

Installation

System requirements

1
RAM — 8 GB minimum (recommended). The default Docker stack runs the portal, MongoDB, and one container per enabled MCP integration. Services such as Memory and Code Search load embedding models (~300 MB each) at startup. On servers with less than ~8 GB RAM you risk out-of-memory kills and unstable behaviour.
2
CPU — 2 vCPU minimum, 4 vCPU recommended. The stack runs the portal, MongoDB, and one container per enabled MCP integration, plus the embedding-model services. As guidance: 2 vCPU is workable for a small pilot with one or two users, while 4 vCPU is a safer baseline for normal daily use with several concurrent users. These are starting points rather than benchmarked limits — heavy agent or embedding workloads may need more.
3
CPU — AVX support required. MongoDB 7 needs a CPU with AVX instructions (typical on Intel Haswell / AMD Ryzen and newer). The installer checks this automatically.
4
Disk — tens of GB free. Docker images for all services add up; leave enough space for images, volumes, and logs.
5
Docker & Docker Compose — required. If Docker is missing when you run the installer as root, it offers to install it for you (after confirmation). To install it yourself first, see the Docker install guide.

Install ClearFox

1
ClearFox is distributed as a Docker stack. During onboarding we send you a registry username and password — you need them to pull the images.
2
On a server with Docker installed, clone the deployment repo and run the installer once. It asks for your registry credentials, logs in, generates local secrets, pulls all images, and starts the stack:
```
git clone https://github.com/clearfox-ai/clearfox-deploy /opt/clearfox
cd /opt/clearfox
sudo ./install.sh
```
3
Back up /opt/clearfox/.env immediately. On first run the installer generates PORTAL_SECRETS_KEY there, on your server, and it is stored nowhere else — we cannot recover it. Lose that file and every secret in MongoDB (integration credentials, OAuth tokens) becomes permanently unreadable. The installer prints the same warning as its very last line.
4
When the installer finishes, open http://localhost:3000 (or your server’s address and port) and complete the setup wizard.
5
Recommended — enable HTTPS so OAuth and SSO work (see HTTPS Requirement below). The installer can set up Caddy for you:
```
cd /opt/clearfox && sudo ./install.sh caddy ai.yourcompany.com
```
6
Manual login (alternative to the installer). If you prefer to manage the stack yourself, log in to the registry and start it manually. First copy .env.example to .env and set PORTAL_SECRETS_KEY and PORTAL_INTERNAL_AUTH_KEY to random 32-byte hex values (openssl rand -hex 32):
```
docker login docker.clearfox.ai -u your-username
docker compose pull
docker compose up -d
```

Getting updates

1
ClearFox ships new versions as updated Docker images. One command does the whole update: it refreshes the compose file, pulls the latest images, restarts the stack, and cleans up the old image versions (they accumulate on disk otherwise):
```
cd /opt/clearfox && git pull && docker compose pull && docker compose up -d && docker image prune -f
```
2
Your .env and data volumes are preserved, and your registry login persists — no need to log in again.
3
Order matters — that is why git pull runs first. Some releases add or remove services; refreshing docker-compose.yml before docker compose pull is what makes Compose fetch the correct set of images. Keep the steps in this order if you ever run them separately.

Customizing the stack

1
The docker-compose.yml in the repo is overwritten on every git pull, so don’t edit it directly. Put your changes in a docker-compose.override.yml next to it — Docker Compose merges it automatically and git pull never touches it.

Example — raise the portal’s memory limit:

# docker-compose.override.yml
services:
  portal:
    mem_limit: 2g

3
Do not override ports. Compose appends to a service’s port list instead of replacing it, so the portal would end up published on 3000 and your new port. To change the published port, set CLEARFOX_PORT=8080 in .env — the compose file reads it ("${CLEARFOX_PORT:-3000}:3000"), and so do the installer’s health check and the Caddyfile it generates. An override-only change would leave both pointing at 3000.
4
Run docker compose up -d as usual — the override is applied on top of the base file. Use docker compose config to preview the merged result.