IT Administrator Manual

v1.2.0 — what changed since this manual was authored

This administrator manual was first written against v1.1.0. The v1.2.0 release (2026-04-23) adds five operator-facing capabilities that are not individually documented in every section below. Where this manual and the CHANGELOG disagree, the CHANGELOG wins. Always treat CHANGELOG.md §[1.2.0] as the authoritative delta.

• T6 at-rest encryption for connector credentials (ENG-001 closed). data_sources.connection_config is now stored as a Fernet envelope (AES-128-CBC + HMAC-SHA256). A new required ENCRYPTION_KEY env var drives the encryption; the installer auto-generates a Fernet key on fresh install and prints a loud "BACK IT UP SEPARATELY FROM YOUR DATABASE" banner. Operator section: USER-MANUAL.md §B.3.2. Spec: UNIFIED-SPEC §8.10. Reversible Alembic migration 019_encrypt_connection_config. Losing the key means losing decryption access to every connector's credentials — no recovery path in v1.2.0.
• T5D install-time portal switch. New PORTAL_MODE env var (private default, public opt-in). Private mode is the existing staff-only posture; public mode exposes exactly three surfaces — landing page, resident-registration path, authenticated records-request submission for UserRole.PUBLIC. Nothing else. Operator section: USER-MANUAL.md §B.3.1. Spec: UNIFIED-SPEC §8.9.
• T5E Windows unsigned double-click installer. Real .exe shipped as a GitHub Release asset (CivicRecordsAI-1.2.0-Setup.exe + .sha256). Unsigned by design per locked signing posture α — SmartScreen will show "Windows protected your PC — Unknown publisher." Remediation: More info → Run anyway, then confirm UAC. Two-shortcut flow: Start CivicRecords AI (daily docker compose up -d) and Install or Repair CivicRecords AI (full bootstrap + model pick + pull). macOS/Linux remain on the guided-script path (install.sh).
• T5C 4-model Gemma 4 installer picker. gemma4:e4b is the default selected model. The fake tags gemma4:12b and gemma4:27b that appeared in earlier hardware-detect scripts have been purged. gemma4:26b / gemma4:31b are still selectable but gated behind an explicit "requires stronger hardware" acknowledgement against the locked 32 GB target profile. The embedding model nomic-embed-text is auto-pulled alongside the selected LLM.
• T5A/T5B operator surface. T5A makes the single-phase adaptive onboarding interview actually persist each answer and transition onboarding_status through the not_started → in_progress → complete lifecycle. T5B auto-seeds 175 state-scoped exemption rules, 5 compliance templates, and 12 notification templates on first boot via app/main.lifespan; idempotent via skip-if-exists so admin customizations survive re-seeds.

Test coverage at v1.2.0: 617 backend pytest + 36 frontend vitest, CI-verified (GitHub Actions run 24859606170 on commit cc06abc). See the v1.2.0 release page for the curated release notes.

1. System Overview

Architecture Summary

CivicRecords AI is a locally-hosted, Docker Compose-based application that assists municipal clerks in processing open records (public records / FOIA) requests. The system runs entirely on-premises with no cloud dependencies, no telemetry, and no outbound data transmission. All AI inference is performed locally via Ollama using open-weight models.

The architecture follows a standard three-tier pattern: a React single-page application serves as the administrative front end, communicating with a FastAPI REST backend, which in turn interfaces with PostgreSQL (with pgvector for semantic search), Redis (for task queuing), and Ollama (for local LLM inference). Asynchronous document ingestion is handled by Celery workers with Redis as the message broker.

For the full architectural diagram and data flow, refer to docs/architecture/system-architecture.html.

Docker Services

Technology Stack

License Compliance

CivicRecords AI is released under the Apache License 2.0. All runtime dependencies use permissive or weak-copyleft licenses (MIT, Apache 2.0, BSD, LGPL, MPL). Redis is pinned to version 7.2 (BSD licensed); version 8.x and later changed to a non-permissive license and must not be used.

2. Hardware Requirements

Minimum Specification

Recommended Specification

GPU Acceleration Support

The installer automatically detects GPU hardware and selects the appropriate Docker Compose overlay. GPU acceleration is optional; the system functions fully on CPU-only hardware.

Performance Target

3. Installation

Prerequisites

• Docker Engine 24.0+ and Docker Compose v2 (included with Docker Desktop on Windows/macOS)
• At least 32 GB RAM available to Docker (configure in Docker Desktop → Settings → Resources)
• 50 GB free disk space
• Network access to Docker Hub during initial installation (for image pulls)
• For GPU acceleration: appropriate drivers installed (AMD ROCm, NVIDIA CUDA, or DirectML)

Windows Installation

Open PowerShell as Administrator in the project directory and run:

.\install.ps1

The script performs the following steps:

1. Verifies Docker Desktop is installed and the daemon is running
2. Verifies Docker Compose v2 is available
3. Creates .env from .env.example and generates a cryptographically random JWT secret
4. Pauses for you to configure admin credentials in .env
5. Runs hardware detection (scripts/detect_hardware.ps1) and writes .env.hardware
6. Selects the appropriate Docker Compose overlay (GPU or host Ollama if applicable)
7. Pulls base Docker images and builds application images
8. Starts PostgreSQL and Redis; waits for database readiness (up to 60 seconds)
9. Runs Alembic database migrations
10. Starts all seven services
11. Waits for the API health endpoint to respond
12. Pulls the embedding model (nomic-embed-text)
13. Prints the recommended language model command and access URLs

Linux Installation (Ubuntu/Debian)

Run from the project directory:

chmod +x install.sh
./install.sh

The script will automatically install Docker and Docker Compose if they are not present on the system. On Linux with AMD GPUs, the script detects ROCm support and applies the docker-compose.gpu.yml overlay for GPU device passthrough.

macOS Installation

Docker Desktop for Mac is required. Install it from docker.com, then run:

chmod +x install.sh
./install.sh

macOS does not support GPU passthrough to Docker containers. All inference runs on CPU.

Post-Installation Verification

After installation completes, verify that all services are healthy:

# Check all container health statuses
docker compose ps
NAME                STATUS              PORTS
civicrecords-api    Up (healthy)        0.0.0.0:8000->8000/tcp
civicrecords-beat   Up
civicrecords-frontend Up (healthy)      0.0.0.0:8080->80/tcp
civicrecords-ollama Up (healthy)
civicrecords-postgres Up (healthy)      5432/tcp
civicrecords-redis  Up (healthy)        6379/tcp
civicrecords-worker Up (healthy)

# Test API health endpoint
curl http://localhost:8000/health
{"status":"ok","version":"1.4.1"}

# Verify OpenAPI documentation is accessible
curl -s http://localhost:8000/docs | head -1

# Verify frontend is serving
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080
200

# Run data sovereignty verification
bash scripts/verify-sovereignty.sh    # Linux/macOS
.\scripts\verify-sovereignty.ps1      # Windows

First Admin Account Setup

The system automatically creates the first administrator account on startup using the credentials specified in the .env file:

• FIRST_ADMIN_EMAIL — the login email for the initial admin (default: admin@example.gov)
• FIRST_ADMIN_PASSWORD — the initial password (must be changed from the default)

After installation, navigate to http://<server-ip>:8080 to access the admin panel and log in with the configured credentials. Change the admin password immediately after first login.

4. Configuration Reference

Environment Variables (.env)

Hardware Detection (.env.hardware)

The installer generates a .env.hardware file with auto-detected values. These variables are consumed by the Docker Compose overlays and are not typically edited manually.

GPU Configuration

GPU support is configured through Docker Compose overlay files:

• docker-compose.gpu.yml — Linux AMD ROCm: passes GPU devices into the Ollama container
• docker-compose.host-ollama.yml — Windows DirectML: replaces containerized Ollama with host-native Ollama for GPU access
• NVIDIA CUDA: use the NVIDIA Container Toolkit and set deploy.resources.reservations.devices in a custom overlay

Docker Compose Overrides

The system supports standard Docker Compose override patterns. To customize resource limits, port mappings, or volume mounts without modifying the base file, create a docker-compose.override.yml:

# docker-compose.override.yml
services:
  api:
    ports:
      - "443:8000"
    deploy:
      resources:
        limits:
          memory: 4G

5. User & Department Administration

Creating Users

User accounts are created exclusively by administrators through the admin API or admin panel. There is no self-registration. This is a deliberate security design: only authorized municipal staff should have access to the system.

# Create a new user via the API
curl -X POST http://localhost:8000/admin/users \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "clerk@city.gov",
    "password": "SecurePassword123!",
    "full_name": "Jane Doe",
    "role": "staff"
  }'

Roles and Permissions

Creating Departments

curl -X POST http://localhost:8000/departments/ \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Public Works", "description": "Roads, water, utilities"}'

Assigning Users to Departments

Use the PATCH /departments/{dept_id} endpoint to update department membership, or assign a department when creating users via the admin panel. A user can belong to one department at a time.

Department Scoping Behavior

• Staff and Read Only users can only search documents and view requests within their assigned department.
• Reviewer and Admin users have cross-department visibility and can view all documents and requests.
• Documents ingested from a data source are associated with the department that owns that data source.
• If a user has no department assigned, they cannot see any department-scoped content (except Admins, who see everything).

Service Accounts for Federation

Service accounts enable machine-to-machine API access for integrations with other municipal systems (e.g., a records management system pushing documents). Service accounts authenticate with API keys rather than JWT tokens.

# Create a service account
curl -X POST http://localhost:8000/service-accounts/ \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "RMS Integration", "description": "Automated document feed from Records Management System"}'

6. Data Source Management

Adding File Directory Sources

A directory data source points to a file system path accessible to the API container. This path must be mounted as a Docker volume.

curl -X POST http://localhost:8000/datasources/ \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "City Council Minutes",
    "source_type": "directory",
    "config": {"path": "/data/council-minutes"}
  }'

Uploading Files

Files can be uploaded directly through the API or the admin panel. Uploaded files are stored in the uploads Docker volume at /tmp/civicrecords-uploads inside the container.

curl -X POST http://localhost:8000/datasources/upload \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -F "file=@meeting-minutes-2025.pdf"

Ingestion Pipeline Overview

1. Discovery — Files in a data source directory are scanned and new/changed files are identified by hash comparison.
2. Parsing — Each file is processed by the appropriate parser based on file extension.
3. Chunking — Parsed text is split into overlapping chunks suitable for embedding and retrieval.
4. Embedding — Each chunk is embedded using the configured embedding model (nomic-embed-text by default) and stored as a vector in pgvector.
5. Indexing — Document metadata and chunk vectors are written to PostgreSQL for both keyword and semantic search.

Ingestion is performed asynchronously by the Celery worker service.

Triggering Ingestion

# Trigger ingestion for a specific data source
curl -X POST http://localhost:8000/datasources/{source_id}/ingest \
  -H "Authorization: Bearer <admin-jwt-token>"

Monitoring Ingestion Status

# View data source statistics including ingestion progress
curl http://localhost:8000/datasources/stats \
  -H "Authorization: Bearer <admin-jwt-token>"

Each document tracks its ingestion status: pending, processing, completed, or failed.

Supported File Formats

Troubleshooting Ingestion Failures

• Document stuck in "processing" — Check that the worker service is running: docker compose ps worker. Restart if needed: docker compose restart worker.
• "Failed" status — Check worker logs: docker compose logs worker --tail 100. Common causes: unsupported file format, corrupt file, or Ollama not responding (for vision model parsing).
• Embedding failures — Verify the embedding model is pulled: docker compose exec ollama ollama list. If nomic-embed-text is missing, pull it.
• Large file timeouts — Very large PDFs (100+ pages) may exceed the default Celery task timeout. Monitor the worker logs for timeout errors.

7. Model Management

Recommended Models

CivicRecords AI is optimized for the Gemma 4 family of open-weight models from Google. These models provide strong instruction-following, good factual accuracy, and are released under permissive licenses suitable for government use.

The installer picker presents all four supported Gemma 4 tags. The default is gemma4:e4b. Only e2b and e4b are supportable at the 32 GB baseline target profile; 26b and 31b require stronger hardware and are gated behind an explicit confirmation in the installer.

Pulling Models via Ollama

# Pull the embedding model (required)
docker compose exec ollama ollama pull nomic-embed-text

# Pull the default chat/vision model
docker compose exec ollama ollama pull gemma4:e4b
# OR a smaller edge model for tighter installs:
docker compose exec ollama ollama pull gemma4:e2b
# OR workstation models (require 48+ GB RAM for 26b, 64+ GB RAM and GPU for 31b):
docker compose exec ollama ollama pull gemma4:26b
docker compose exec ollama ollama pull gemma4:31b

# If using host-native Ollama (Windows GPU):
ollama pull nomic-embed-text
ollama pull gemma4:e4b

# Verify installed models
docker compose exec ollama ollama list

Model Registry

The model registry tracks compliance metadata for every model used in the system. This supports audit and governance requirements by recording which model version produced each analysis.

# View registered models
curl http://localhost:8000/admin/models/registry \
  -H "Authorization: Bearer <admin-jwt-token>"

# Register a new model with compliance metadata
curl -X POST http://localhost:8000/admin/models/registry \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "gemma4:e4b",
    "version": "latest",
    "license": "Apache 2.0",
    "provider": "Google",
    "purpose": "Records query analysis and exemption reasoning"
  }'

Switching Models

To change the active model, update the CHAT_MODEL and/or VISION_MODEL variables in .env and restart the API service:

# Edit .env to set the new model (any Ollama tag; picker defaults are four Gemma 4 tags)
# CHAT_MODEL=gemma4:e2b
# VISION_MODEL=gemma4:e2b

# Restart API to pick up the change
docker compose restart api

Embedding Model

The embedding model (nomic-embed-text by default) converts document chunks into vector representations for semantic search. Changing the embedding model requires re-ingesting all documents to rebuild the vector index.

Model Resource Requirements

8. Exemption Rules Administration

How the Rules Engine Works

CivicRecords AI uses a rules-primary, LLM-secondary architecture for exemption detection. When a document is scanned for potential exemptions (e.g., personal privacy, law enforcement confidentiality, trade secrets):

1. Deterministic rules are evaluated first. These are pattern-based rules tied to specific state statutes. Each rule defines keywords, patterns, and the statutory citation it implements.
2. LLM analysis runs second, using the language model to identify exemptions that pattern matching may miss. The LLM provides reasoning for each flagged exemption.
3. Human review is always required. The system flags potential exemptions but never automatically redacts or denies records. A human reviewer must accept, modify, or dismiss each flag.

50-State Coverage

The system ships with approximately 180 exemption rules covering all 50 U.S. states plus federal FOIA categories. Rules are seeded from the backend/scripts/seed_rules.py script and stored in the exemption_rules database table.

Viewing Rules by State

# List all exemption rules (filterable by state)
curl "http://localhost:8000/exemptions/rules/?state=CO" \
  -H "Authorization: Bearer <admin-jwt-token>"

Creating Custom Rules

curl -X POST http://localhost:8000/exemptions/rules/ \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "CO",
    "statute": "CRS 24-72-204(3)(a)(IV)",
    "category": "Trade Secrets",
    "description": "Trade secrets, privileged information, confidential commercial data",
    "keywords": ["trade secret", "proprietary", "confidential commercial"],
    "rule_type": "pattern",
    "enabled": true
  }'

Enabling / Disabling Rules

# Disable a specific rule
curl -X PATCH http://localhost:8000/exemptions/rules/{rule_id} \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Running the Seed Script

To populate or reset the exemption rules database with the built-in rule set:

docker compose exec api python -m scripts.seed_rules

9. Compliance & Audit

Hash-Chained Audit Log Architecture

Every significant action in the system (login, document access, search queries, exemption decisions, request status changes) generates an immutable audit log entry. Each entry includes a SHA-256 hash of its contents chained to the previous entry's hash, creating a tamper-evident log structure similar to a blockchain.

If any entry is modified or deleted, the chain verification will fail at that point, providing cryptographic proof of tampering. This design satisfies records retention and legal discovery requirements.

Audit Log Retention

The default retention period is 1,095 days (3 years), configurable via the AUDIT_RETENTION_DAYS environment variable. Entries older than this threshold are eligible for archival.

Verifying Audit Chain Integrity

# Verify the audit log hash chain is intact
curl http://localhost:8000/audit/verify \
  -H "Authorization: Bearer <admin-jwt-token>"
{"valid": true, "entries_checked": 14523, "chain_intact": true}

Exporting Audit Logs

# Export audit logs (supports CSV and JSON formats)
curl "http://localhost:8000/audit/export?format=csv&start_date=2026-01-01&end_date=2026-03-31" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -o audit-q1-2026.csv

# JSON export
curl "http://localhost:8000/audit/export?format=json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -o audit-full.json

Compliance Template Documents

The system includes five compliance template documents stored at backend/compliance_templates/:

Rendering Templates with City Profile

Templates contain placeholder variables (city name, contact information, etc.) that are populated from the city profile:

# Set up the city profile first
curl -X POST http://localhost:8000/city-profile \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "city_name": "City of Boulder",
    "state": "CO",
    "contact_email": "records@bouldercolorado.gov"
  }'

# Render a template with city profile data
curl http://localhost:8000/exemptions/templates/{template_id}/render \
  -H "Authorization: Bearer <admin-jwt-token>"

Data Sovereignty Verification

Run the sovereignty verification script to confirm that no data leaves the local system:

# Linux / macOS
bash scripts/verify-sovereignty.sh

# Windows
.\scripts\verify-sovereignty.ps1

This script inspects Docker network configuration, DNS resolution settings, and container firewall rules to verify that no container has outbound internet access.

CAIA Classification

Under the Colorado Artificial Intelligence Act (SB 24-205), CivicRecords AI is classified as not high-risk. The system does not autonomously make or substantially contribute to consequential decisions. All exemption flags and document classifications require human review and approval before any action is taken. The system is an assistive tool, not a decision-maker. The full impact assessment is documented in backend/compliance_templates/caia-impact-assessment.md.

10. Security

Network Configuration

By default, only the API (port 8000) and frontend (port 8080) services expose ports to the host. All other services (PostgreSQL, Redis, Ollama) communicate over Docker's internal network and are not accessible from outside the Docker Compose stack.

HTTPS / TLS Setup

CivicRecords AI does not include a built-in TLS certificate. To enable HTTPS, place a reverse proxy in front of the application:

# Example: nginx reverse proxy configuration
server {
    listen 443 ssl;
    server_name records.city.gov;

    ssl_certificate     /etc/ssl/certs/records.city.gov.crt;
    ssl_certificate_key /etc/ssl/private/records.city.gov.key;

    location /api/ {
        proxy_pass http://127.0.0.1:8000/;
    }
    location / {
        proxy_pass http://127.0.0.1:8080/;
    }
}

JWT Secret Management

• The JWT secret must be at least 32 characters long.
• The application refuses to start if the JWT secret is set to a known insecure default (CHANGE-ME, empty string, or the placeholder value).
• Generate a secure secret: openssl rand -hex 32
• Store the .env file with restricted permissions: chmod 600 .env
• If the JWT secret is rotated, all existing sessions are invalidated and users must re-authenticate.

Login Rate Limiting

The login endpoint (POST /auth/jwt/login) is rate-limited to 5 requests per minute per IP address. Exceeding this limit returns HTTP 429 (Too Many Requests). The rate limiter uses in-memory tracking with a maximum of 10,000 tracked IPs and automatic expiry of stale entries.

No Default Passwords

The installer generates a random JWT secret and forces the administrator to set the initial admin password before the first start. The application will not start with placeholder credentials.

No Telemetry or Outbound Connections

CivicRecords AI makes zero outbound network connections during normal operation. There is no telemetry, no analytics, no update checking, and no "phone home" behavior. All AI inference happens locally via Ollama. The system can operate on a completely air-gapped network after initial Docker image pulls.

Role-Based Access Control

All API endpoints enforce role-based access control (RBAC) using the require_role() dependency. See the User & Department Administration section for the full role permissions matrix. Key restrictions:

• User management endpoints (/admin/*) require the admin role.
• Audit log export requires the admin role.
• Document search is scoped by department for staff and read_only roles.
• Request approval workflows require the reviewer or admin role.

Service Account API Key Hashing

Service account API keys are hashed with bcrypt before storage. The plaintext key is returned exactly once at creation time and is never stored or logged. Authentication of service account requests validates the provided key against the stored hash.

11. Backup & Recovery

What to Back Up

PostgreSQL Backup

# Create a full database dump
docker compose exec -T postgres pg_dump -U civicrecords civicrecords > backup-$(date +%Y%m%d).sql

# Compressed backup (recommended for large databases)
docker compose exec -T postgres pg_dump -U civicrecords -Fc civicrecords > backup-$(date +%Y%m%d).dump

# Back up environment files
cp .env .env.backup-$(date +%Y%m%d)

# Back up uploaded documents volume
docker run --rm -v civicrecords-ai_uploads:/data -v $(pwd)/backups:/backup alpine \
  tar czf /backup/uploads-$(date +%Y%m%d).tar.gz -C /data .

Restore Procedure

# 1. Stop the application
docker compose down

# 2. Start only the database
docker compose up -d postgres

# 3. Wait for database readiness
docker compose exec -T postgres pg_isready -U civicrecords

# 4. Drop and recreate the database
docker compose exec -T postgres dropdb -U civicrecords civicrecords
docker compose exec -T postgres createdb -U civicrecords civicrecords

# 5a. Restore from SQL dump
docker compose exec -T postgres psql -U civicrecords civicrecords < backup-20260401.sql

# 5b. OR restore from compressed dump
docker compose exec -T postgres pg_restore -U civicrecords -d civicrecords < backup-20260401.dump

# 6. Start all services
docker compose up -d

# 7. Verify health
curl http://localhost:8000/health

Backup Schedule Recommendations

12. Monitoring & Troubleshooting

Health Endpoint

curl http://localhost:8000/health
{"status":"ok","version":"1.4.1"}

The GET /health endpoint returns HTTP 200 with the application version when the API is operational. Use this for load balancer health checks and monitoring systems.

Docker Service Health Checks

# View health status of all services
docker compose ps

# View health check logs for a specific service
docker inspect --format='{{json .State.Health}}' civicrecords-api-1

Common Issues

Log Locations

# API server logs
docker compose logs api --tail 100 -f

# Worker (ingestion) logs
docker compose logs worker --tail 100 -f

# Database logs
docker compose logs postgres --tail 50

# Ollama inference logs
docker compose logs ollama --tail 50

# All services combined
docker compose logs --tail 200 -f

Checking Ollama Model Status

docker compose exec ollama ollama list
NAME                  ID           SIZE     MODIFIED
nomic-embed-text      274b5616...  274 MB   3 days ago
gemma4:e4b            c6eb396d...  9.6 GB   3 days ago

Database Connectivity Checks

# Test database connectivity from the API container
docker compose exec api python -c "
from app.database import engine
import asyncio
async def check():
    async with engine.connect() as conn:
        result = await conn.execute(text('SELECT 1'))
        print('Database OK:', result.scalar())
from sqlalchemy import text
asyncio.run(check())
"

# Direct PostgreSQL check
docker compose exec postgres pg_isready -U civicrecords
/var/run/postgresql:5432 - accepting connections

13. Upgrading

Upgrade Procedure

1. Back up the database before any upgrade:

   docker compose exec -T postgres pg_dump -U civicrecords -Fc civicrecords > pre-upgrade-backup.dump

2. Pull the latest code:

   git pull origin main

3. Rebuild Docker images:

   docker compose build

4. Run database migrations:

   docker compose run --rm api alembic upgrade head

5. Restart all services:

   docker compose up -d

6. Verify health:

   curl http://localhost:8000/health

Database Migrations

CivicRecords AI uses Alembic for database schema migrations. Migration files are stored in backend/alembic/versions/. Key commands:

# Apply all pending migrations
docker compose exec api alembic upgrade head

# Check current migration version
docker compose exec api alembic current

# View migration history
docker compose exec api alembic history

Version Compatibility

Always upgrade sequentially through minor versions. Skipping major versions may result in migration conflicts. Check the CHANGELOG.md for breaking changes between versions.

Rollback Procedure

1. Stop all services:

   docker compose down

2. Restore the database from the pre-upgrade backup:

   docker compose up -d postgres
   docker compose exec -T postgres dropdb -U civicrecords civicrecords
   docker compose exec -T postgres createdb -U civicrecords civicrecords
   docker compose exec -T postgres pg_restore -U civicrecords -d civicrecords < pre-upgrade-backup.dump

3. Check out the previous version:

   git checkout v1.0.0  # Replace with the target version tag

4. Rebuild and restart:

   docker compose build
   docker compose up -d

14. Appendices

Appendix A: Complete API Endpoint Reference

Appendix B: Database Schema Overview

The system uses 29 PostgreSQL tables. Key tables and their relationships:

Appendix C: Docker Compose Environment Variables

The following environment variables are set within docker-compose.yml for infrastructure services:

Application services (api, worker, beat) load their configuration from the .env file via the env_file directive in docker-compose.yml.

Appendix D: Supported Platforms Matrix