Skip to main content

Installation

The fastest way to run Campbooks is with Docker — docker compose up starts the whole stack (Postgres with pgvector, the web app, and a background worker). If you want to hack on the code instead, there's a from-source path below.

Just deploying it for real? This page gets you running locally. For a production server with a domain and HTTPS, follow the Self-Hosting guide.

Option A — Docker (recommended)​

Prerequisites​

  • Docker and the Docker Compose plugin (Docker Desktop, or Docker Engine ≥ 24 with docker compose)
  • About 2 GB of free RAM
  • openssl (already present on macOS and Linux) for generating secrets

That's it — Ruby, Postgres, and everything else run inside the containers.

1. Clone and configure​

git clone https://github.com/notacamp/campbooks.git
cd campbooks

cp .env.example .env
bin/generate-secrets   # fills SECRET_KEY_BASE, the encryption keys, and the DB password

bin/generate-secrets writes the four required secrets and the database password into .env for you.

The encryption keys are required. SECRET_KEY_BASE, ACTIVE_RECORD_PRIMARY_KEY, ACTIVE_RECORD_DETERMINISTIC_KEY, and ACTIVE_RECORD_KEY_DERIVATION_SALT must all be set or the app won't boot. The encryption keys protect OAuth tokens and AI keys at rest — bin/generate-secrets creates them; to do it by hand, use openssl rand -hex 64 for SECRET_KEY_BASE and openssl rand -hex 16 for the three AR keys.

2. (Optional) add an AI key and integrations​

Open .env and add at least one AI provider key to unlock triage, Scout, draft replies, and document analysis — and any OAuth credentials for the mailboxes/integrations you want. Everything here is optional; the app runs without it.

# any one of these enables text AI (triage, Scout, draft replies)
OPENAI_API_KEY=...      # also unlocks document/vision analysis + embeddings
ANTHROPIC_API_KEY=...
MISTRAL_API_KEY=...     # EU-hosted

3. Start it​

docker compose up -d --build

# first boot creates the databases and runs migrations — watch it come up
docker compose logs -f web

Open http://localhost:3000 and register the first account — on a self-hosted instance signup is open, and the first user creates the workspace.

Seed login. First boot also seeds a demo workspace you can sign in to: admin@example.com / changeme123 (and partner@example.com). Change that password after first login, or set SEED_PASSWORD in .env before the first boot.

To stop: docker compose down (add -v to also delete the database and uploaded files).

Option B — From source (for development)​

Prefer to run the app directly — to contribute, say? You'll need:

  • Ruby 3.2.2 (see .ruby-version)
  • PostgreSQL 16+ with the pgvector extension (a migration runs CREATE EXTENSION vector, so a vanilla Postgres won't do)

No Node.js and no Redis are required — JavaScript is served through import maps, Tailwind compiles via a standalone binary, and jobs/cache/cable all run on Postgres via the Solid adapters.

git clone https://github.com/notacamp/campbooks.git
cd campbooks
bin/setup            # installs gems, prepares the database, and seeds it

Configure secrets in .env (as above), then run the web server and the worker:

bin/dev                          # web + Tailwind watcher (Procfile.dev)
bin/rails solid_queue:start      # background worker (email scanning, AI, indexing)

Open http://localhost:3000 and sign in with a seed user.

Next step​

See the Deployment guide to run Campbooks on a server with a reverse proxy and HTTPS.

Last updated on