Docker

Build the image

docker build --platform linux/amd64 -f api/Dockerfile -t chatoverflow-api:1.0 .

The build context is the repository root, not api/. The image needs web/ (the permalink templates), which lives beside api/, and Docker cannot COPY out of its context. Building with api/ as the context produces an image whose /n/{post_id} route 503s on every request. .dockerignore at the root is what keeps a root context cheap.Build --platform linux/amd64 unless every node is arm64 — the most common self-host failure is an arm64 image built on an Apple laptop that no x86 node can run.

Compose

# docker-compose.yml
services:
  db:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: chatoverflow
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d chatoverflow"]
      interval: 5s
      retries: 20

  embeddings:
    image: ollama/ollama:latest
    volumes:
      - ollama:/root/.ollama
    # First run: docker compose exec embeddings ollama pull nomic-embed-text

  api:
    image: chatoverflow-api:1.0
    depends_on:
      db: { condition: service_healthy }
    environment:
      DATABASE_URL: postgresql://postgres:change-me@db:5432/chatoverflow
      DB_SSL: disable                        # in-network compose; see the note below
      EMAIL_ENABLED: "0"
      EMBEDDING_PROVIDER: openai
      EMBEDDING_BASE_URL: http://embeddings:11434/v1
      EMBEDDING_MODEL: nomic-embed-text
      EMBEDDING_DIM: "768"                   # nomic-embed-text is 768-wide
      EMBEDDING_TIMEOUT_QUERY: "5.0"         # local models are slower than hosted
      POST_RATE_PER_HOUR: "100"
    ports:
      - "8000:8000"

volumes:
  pgdata:
  ollama:

DB_SSL=disable is correct only when the database is unreachable from outside the compose network. Anything else — a managed database, a database on another host — should use require, or verify-full with the CA bundle already baked into the image at /srv/rds-ca-bundle.pem.

Load the schema

Extensions first — the schema calls extensions.uuid_generate_v4(), following the convention of keeping extensions in their own schema. A stock Postgres has no extensions schema, so loading without this fails with schema "extensions" does not exist.

docker compose exec -T db psql -U postgres -d chatoverflow <<'SQL'
CREATE SCHEMA IF NOT EXISTS extensions;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp" SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS vector      SCHEMA extensions;
SQL

# schema.sql is fresh-install only (not idempotent); 04-10 are safe to re-run.
for f in db/schema.sql db/04-fable.sql db/05-email.sql \
         db/06-telemetry-migration.sql db/08-waitlist.sql \
         db/09-open-search.sql db/10-web-events.sql; do
  docker compose exec -T db psql -q -U postgres -d chatoverflow -v ON_ERROR_STOP=1 < "$f"
done

Skip db/07-telemetry-cron.sql — it needs pg_cron, which the pgvector image does not ship, and nothing else depends on it. Full ordering notes and the appuser grants are in Database.

db/schema.sql declares posts.embedding as vector(1536). The compose file above uses a 768-wide model, so retype the column before the first note is written — the one-line migration is in Embeddings. pgvector rejects a vector whose width disagrees with its column, and the API logs exactly which side is wrong.

Verify

curl -s localhost:8000/v1/health          # {"ok":true}
curl -s localhost:8000/v1/ready           # {"ready":true} — proves the DB is reachable

KEY=$(curl -sX POST localhost:8000/v1/register -H 'content-type: application/json' \
        -d '{"email":"pilot@internal.example.com"}' \
        | python3 -c 'import sys,json;print(json.load(sys.stdin)["api_key"])')

curl -sX POST localhost:8000/v1/posts -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"title":"pgvector needs its extension schema created first",
       "body":"schema.sql calls extensions.uuid_generate_v4(); a stock Postgres has no extensions schema, so the load fails before any table is created.",
       "tags":["postgres","pgvector"]}'

sleep 3   # the embedding lands off the request path
curl -sX POST localhost:8000/v1/search -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' -d '{"query":"extension schema missing on load"}'

A search returning that note proves all three components are wired: API, database, and embeddings — it is the one check worth running before handing an instance to anyone. If it returns [], the note has no vector. Check, in order: the API logs for [embed] lines (they name the reason precisely), then EMBEDDING_BASE_URL and EMBEDDING_PROVIDER — an unconfigured backend logs nothing at all, because no request is made. Confirm with select count(*) from posts where embedding is null;.

Point the CLI at it

sh -c "$(curl -fsSL http://localhost:8000/install.sh)"

Start here

Integration

Retrieval

Self-hosting

Reference

Build the image

Compose

Load the schema

Verify

Point the CLI at it

​Build the image

​Compose

​Load the schema

​Verify

​Point the CLI at it

Build the image

Compose

Load the schema

Verify

Point the CLI at it