Configure Core Services

Configure the Raw to Knowledge API service, PostgreSQL database, and Redis broker. These three components form the mandatory foundation. Graph, vector, and LLM features are optional and degrade gracefully when not configured.

Prerequisites

Requirement	Version	Notes
Python	3.12	Required. Tested on CPython 3.12.
PostgreSQL	16	Primary data store. Native or Docker.
Redis	7	Celery broker and validation queue. Native or Docker.
uv or pip	Current	Dependency installer.

---

Step 1: Install Python dependencies

From the repository root:

pip install -e ".[dev]"

This installs the Raw to Knowledge package in editable mode along with all development dependencies (pytest, Alembic CLI, linters).

---

Step 2: Set required environment variables

Raw to Knowledge reads configuration exclusively from environment variables via pydantic-settings. At minimum, set:

export DATABASE_URL="postgresql+asyncpg://raw_to_knowledge:raw_to_knowledge@localhost/raw_to_knowledge"
export REDIS_URL="redis://localhost:6379/0"

Note: DATABASE_URL must use the asyncpg driver prefix (postgresql+asyncpg://). The synchronous postgresql:// driver will cause startup failures because SQLAlchemy is configured for async operation.

For a full list of supported variables, see the Environment Variables Reference.

---

Step 3: Start PostgreSQL and Redis

Option A: Docker Compose (recommended for local development)

Create a docker-compose.yml in your working directory with the following content, then run docker compose up -d:

version: "3.9"
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: raw_to_knowledge
      POSTGRES_PASSWORD: raw_to_knowledge
      POSTGRES_DB: raw_to_knowledge
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"

volumes:
  postgres_data:

docker compose up -d

Option B: Native services

Start PostgreSQL and Redis using your operating system's service manager (systemd, Homebrew services, etc.), then create the database and user manually:

createuser -s raw_to_knowledge
createdb -O raw_to_knowledge raw_to_knowledge
psql -U raw_to_knowledge -c "ALTER USER raw_to_knowledge WITH PASSWORD 'raw_to_knowledge';"

---

Step 4: Run Alembic migrations

Apply all database migrations. The migration chain currently runs through revision 005, which creates all tables including the generation and graph schemas:

alembic upgrade head

Expected output ends with:

INFO  [alembic.runtime.migration] Running upgrade ... -> 005, add generation schema

If the database already contains the current schema, Alembic will report no changes and exit cleanly.

---

Step 5: Start the API service

uvicorn raw_to_knowledge.main:app --host 0.0.0.0 --port 8000

For production, add --workers 4 and run behind a reverse proxy (nginx, Caddy). For development, add --reload for hot reloading.

---

Step 6: Verify the health endpoint

curl -s http://localhost:8000/health | python3 -m json.tool

Expected response:

{
  "status": "ok",
  "version": "0.8.0",
  "db": "ok"
}

If "db" is "error", the service cannot reach PostgreSQL. Check DATABASE_URL and confirm the database is running.

---

Step 7: Verify the OpenAPI UI

Open http://localhost:8000/docs in a browser. The interactive Swagger UI should load and list all API routes. This confirms the application is fully initialized.

---

What works without optional services

Note: The service starts and serves requests without Neo4j, Weaviate, or an LLM configured. The core intake, validation, and registry path operates fully on PostgreSQL and Redis alone. Graph and generation features will return errors for their specific endpoints but will not prevent other endpoints from functioning.

Feature area	Requires
Artifact ingest and extraction	PostgreSQL, Redis
Classification	PostgreSQL
Validation workflow	PostgreSQL, Redis
Registry publish and readout	PostgreSQL
Semantic retrieval	Weaviate
Answer generation	Weaviate + OpenAI
Contradiction detection	Neo4j
Confluence/Jira RAG	Connector credentials