Installation

TruthKeeper can be installed as a Python package, run via Docker, or deployed to cloud platforms.

Requirements

  • Python 3.11 or higher
  • pip, uv, or poetry package manager
  • (Production) PostgreSQL 15+ with pgvector extension

Quick Install

Using pip

pip install truthkeeper

Using uv (recommended)

uv add truthkeeper

Using poetry

poetry add truthkeeper

From Source

git clone https://github.com/SimplyLiz/truthkeeper.git
cd truthkeeper
pip install -e ".[dev]"

Docker

Using Pre-built Image

docker pull ghcr.io/simplyliz/truthkeeper:latest

docker run -p 8000:8000 \
  -e DATABASE_URL=sqlite:///./data/truthkeeper.db \
  -v $(pwd)/data:/app/data \
  ghcr.io/simplyliz/truthkeeper:latest

Building from Source

git clone https://github.com/SimplyLiz/truthkeeper.git
cd truthkeeper
docker build -t truthkeeper .
docker run -p 8000:8000 truthkeeper

Docker Compose

For production with PostgreSQL:

version: '3.8'

services:
  truthkeeper:
    image: ghcr.io/simplyliz/truthkeeper:latest
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://truthkeeper:secret@db:5432/truthkeeper
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      - db

  db:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_USER=truthkeeper
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=truthkeeper
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
docker compose up -d

Configuration

Create a .env file or set environment variables:

# Database
DATABASE_URL=sqlite:///./truthkeeper.db
# Or for PostgreSQL:
# DATABASE_URL=postgresql://user:pass@localhost:5432/truthkeeper

# Server
TRUTHKEEPER_HOST=0.0.0.0
TRUTHKEEPER_PORT=8000
TRUTHKEEPER_WORKERS=4

# Verification (optional)
OPENAI_API_KEY=sk-...              # For MiniCheck
ANTHROPIC_API_KEY=sk-ant-...       # Alternative LLM

# Security
TRUTHKEEPER_API_KEY_SALT=random-secret-string
TRUTHKEEPER_CORS_ORIGINS=http://localhost:3000

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json

Database Setup

SQLite (Development)

No additional setup required. TruthKeeper will create the database file automatically.

DATABASE_URL=sqlite:///./truthkeeper.db

PostgreSQL (Production)

  1. Install PostgreSQL 15+ with pgvector extension
  2. Create database and enable extension
  3. Run migrations
# Create database
createdb truthkeeper

# Enable pgvector (requires superuser)
psql truthkeeper -c "CREATE EXTENSION vector;"

# Run migrations
truthkeeper db migrate

Verify Installation

# Check version
truthkeeper --version

# Run health check
truthkeeper health

# Start server
truthkeeper serve

# Test the API
curl http://localhost:8000/api/v1/health

Cloud Deployment

Railway

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

Vercel (API only)

TruthKeeper can run as serverless functions on Vercel:

vercel deploy

Fly.io

flyctl launch
flyctl deploy

Next Steps