Skip to content

Installation

Jump to bottom
John R. D'Orazio edited this page Feb 18, 2026 · 4 revisions

Installation

This guide walks you through setting up the OntoKit API for local development. Choose between two deployment modes:

  • Full Docker Mode - Everything runs in Docker containers (simpler setup)
  • Hybrid Mode - Infrastructure in Docker, API on host (better for debugging)

1. Clone the Repository

git clone https://github.com/JohnRDOrazio/ontokit-api.git
cd ontokit-api

Option A: Full Docker Mode (Recommended for Quick Start)

This mode runs everything in Docker, including the API. Best for trying things out quickly.

Start All Services

docker compose up -d

This starts:

  • PostgreSQL (port 5432) - Shared database for Zitadel and OntoKit
  • Redis (port 6379) - Caching and pub/sub
  • MinIO (port 9000/9001) - Object storage
  • Zitadel (port 8080/8081) - Identity provider
  • OntoKit API (port 8000) - FastAPI backend

Verify all services are running:

docker compose ps

All services should show as "healthy" or "running".

Run Database Migrations

docker compose exec api alembic upgrade head

Set Up Zitadel Authentication

Run the setup script to create OIDC applications and configure credentials:

./scripts/setup-zitadel.sh --update-env

This script automatically:

  1. Waits for Zitadel to be ready
  2. Creates the "OntoKit" project and OIDC application
  3. Updates both ontokit-api/.env and ontokit-web/.env.local with credentials
  4. Prompts to recreate the API container

After the script completes, recreate the API and worker containers to pick up the new credentials:

docker compose up -d --force-recreate api worker

See Authentication for detailed instructions and troubleshooting.

Verify Installation

curl http://localhost:8000/health
# Expected: {"status": "healthy"}

That's it! The API is ready to use.

Option B: Hybrid Mode (Recommended for Development)

This mode runs infrastructure in Docker while the API runs on your host machine. Best for active development with hot reload and IDE debugging.

2. Start Infrastructure Services

Use the production compose file which excludes the API service:

docker compose -f compose.prod.yaml up -d

This starts:

  • PostgreSQL (port 5432) - Shared database for Zitadel and OntoKit
  • Redis (port 6379) - Caching and pub/sub
  • MinIO (port 9000/9001) - Object storage
  • Zitadel (port 8080/8081) - Identity provider

Verify all services are running:

docker compose -f compose.prod.yaml ps

All services should show as "healthy" or "running".

Wait for Zitadel

Zitadel takes a moment to initialize. Wait until it's ready:

# Check Zitadel health
curl http://localhost:8080/debug/ready

You should see a 200 OK response.

3. Create Python Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate it
# On Linux/macOS:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

You should see (.venv) in your terminal prompt.

4. Install Dependencies

# Install the package with development dependencies
pip install -e ".[dev]"

This installs:

  • FastAPI, Uvicorn, Pydantic
  • SQLAlchemy, asyncpg, Alembic
  • RDFLib, OWLReady2
  • Development tools (pytest, ruff, mypy)

5. Configure Environment

Copy the example environment file:

cp .env.example .env

The default .env works for hybrid mode (API on host, infrastructure in Docker):

# Database - connects to shared PostgreSQL container
DATABASE_URL=postgresql+asyncpg://ontokit:ontokit@localhost:5432/ontokit

# Redis
REDIS_URL=redis://localhost:6379/0

# MinIO
MINIO_ENDPOINT=localhost:9000

# Zitadel - you'll add client credentials after setup
ZITADEL_ISSUER=http://localhost:8080
ZITADEL_CLIENT_ID=
ZITADEL_CLIENT_SECRET=

See Configuration for all available options.

6. Set Up Zitadel (Authentication)

Zitadel needs to be configured with OIDC applications for the API and web frontend.

Run the setup script:

./scripts/setup-zitadel.sh --update-env

This automatically creates the OIDC applications in Zitadel and updates both ontokit-api/.env and ontokit-web/.env.local with the credentials.

Note: If you reset the database with docker compose down -v, you'll need to run this script again to recreate the applications. See Authentication#Troubleshooting for common issues.

For manual setup instructions, see Authentication#Manual-Setup.

7. Run Database Migrations

Create the database tables:

alembic upgrade head

You should see output like:

INFO  [alembic.runtime.migration] Running upgrade  -> abc123, Add projects and project_members tables

8. Start the Development Server

uvicorn ontokit.main:app --reload --host 0.0.0.0 --port 8000

Or simply:

uvicorn ontokit.main:app --reload

The API is now running at http://localhost:8000

Verify Installation

Check API Health

curl http://localhost:8000/health

Expected response:

{"status": "healthy"}

View API Documentation

Open http://localhost:8000/docs in your browser to see the interactive Swagger UI.

Test Projects Endpoint

curl http://localhost:8000/api/v1/projects

Expected response:

{"items": [], "total": 0, "skip": 0, "limit": 20}

Database Architecture

The stack uses a single PostgreSQL instance with multiple databases:

Database User Purpose
zitadel zitadel Zitadel identity data
ontokit ontokit Application data (projects, ontologies, etc.)

The scripts/init-db.sh script automatically creates both databases when the PostgreSQL container first starts.

Summary

Your development environment is now ready:

Service URL
OntoKit API http://localhost:8000
API Docs (Swagger) http://localhost:8000/docs
API Docs (ReDoc) http://localhost:8000/redoc
Zitadel Console http://localhost:8080/ui/console
MinIO Console http://localhost:9001
Mailpit (Email Testing) http://localhost:8025

Default Zitadel Admin: admin@ontokit.localhost / Admin123!

Troubleshooting

"Connection refused" errors

Ensure Docker services are running:

docker compose ps  # or docker compose -f compose.prod.yaml ps

Database migration fails

Check PostgreSQL is ready:

docker compose logs postgres

Ensure the ontokit database exists:

docker compose exec postgres psql -U postgres -c "\l"

Zitadel login issues

See Authentication#Troubleshooting for common authentication problems including:

  • "App not found" errors
  • "Unknown error occurred" on login
  • Token validation failures

After resetting the database

If you ran docker compose down -v, you need to:

  1. Start services: docker compose up -d
  2. Re-run the setup script: ./scripts/setup-zitadel.sh --update-env
  3. Recreate API/worker containers: docker compose up -d --force-recreate api worker

Next Steps

Getting Started

Development

Features

Help

Clone this wiki locally