SETUP.md

ObservaKit Setup Guide

1. Introduction

ObservaKit is a self-hosted data observability platform for monitoring data pipelines, freshness, schema drift, alerts, and overall data quality.

---

2. Prerequisites

Before starting, install the following:

• Docker Desktop
• Git
• VS Code
• Python 3.10+

Ensure Docker Compose V2 is installed.

Verify using:

docker compose version

Windows Docker Issue

If Docker shows:

WSL needs updating

Run:

wsl --update

Then restart Docker Desktop.

Docker Build Network Error

If Docker shows:

Unable to connect to deb.debian.org

Retry the docker compose command again. Temporary network issues during image build may cause package installation failures.

---

3. Fork the Repository

1. Open the original repository:

https://github.com/willowvibe/ObservaKit

2. Click the "Fork" button.

3. Create your own copy of the repository.

---

4. Clone Repository

git clone https://github.com/YOUR_USERNAME/ObservaKit.git

cd ObservaKit

---

5. Configure Environment

Windows Setup

copy .env.example .env

Linux/macOS Setup

cp .env.example .env

This creates a .env file from the example template.

---

6. Run the Project

Start the application using Docker Compose:

docker compose up --build

The initial build may take a few minutes depending on your internet connection.

---

7. Verify Installation

After starting the containers, verify that ObservaKit is running by opening:

http://localhost:8000/docs

If the Swagger UI loads successfully, the backend service is running correctly.

The endpoint:

http://localhost:8000/ui

may not be enabled in the current configuration and can return:

{"detail":"Not Found"}

Check Running Containers

docker ps

Expected running containers:

• observakit-backend
• observakit-postgres

Default ports:

• Backend: 8000
• PostgreSQL: 5433

---

8. Expected Result

After successful startup:

• Swagger API documentation should be available at:

http://localhost:8000/docs

• PostgreSQL container should be running successfully

• Backend service should be accessible on port 8000

• Docker containers should appear in:

docker ps