Getting Started: A Developer's Guide¶

Welcome to Labeeb

This guide provides a complete walkthrough for setting up the Labeeb platform for local development. We'll cover the initial platform-wide setup and then dive into the specific steps for each microservice.

1. Prerequisites¶

Before you begin, make sure you have the following installed:

Docker & Docker Compose: The primary tools for running the containerized services.
Git: For cloning the repository.
A code editor: Such as VS Code with the Docker and Remote Development extensions.

2. Platform-Wide First-Time Setup¶

This procedure builds and initializes the entire platform from a fresh checkout. You only need to do this once.

Configure Environment

Create your local .env file from the template. This file holds the master configuration for the Docker environment.
```
cp .env.example .env
```
Build & Start Services

Build the Docker images and start all services in the background. The first build will take a few minutes.
```
docker compose up -d --build
```
Initialize Database

Run the Laravel database migrations to create all the required tables for the API service.
```
docker compose exec api php artisan migrate
```
Bootstrap & Verify Search

Set up the OpenSearch indices, pipelines, and templates, then run a smoke test to verify the search configuration.
```
bash tools/search/install.sh
bash tools/search/smoke.sh
```

3. Service-Specific Setup & Verification¶

After the initial setup, you may need to perform service-specific tasks. Here’s how to get started with each core service.

API Service

The API service is the central nervous system of the platform, handling data processing, business logic, and client-facing communication.

1. Configure Environment: Create your local .env file for the API service from its template.
```
cp api/.env.example api/.env
```
2. Run Migrations:
```
docker compose exec api php artisan migrate
```
3. Install a new PHP package (example):
```
docker compose exec api composer require spatie/laravel-data
```
AI-Box Service

The AI-Box powers evidence retrieval and handles all ML-powered tasks. It implements hybrid search and fact-checking tools.

1. Configure Environment: Create your local .env file for the AI-Box service from its template.
```
cp ai-box/.env.example ai-box/.env
```
2. Build & Start Service:
```
docker compose build ai-box
docker compose up -d ai-box
```
3. Run a smoke test (hybrid search query):
```
curl -s localhost:8001/retrieve -H 'content-type: application/json' \
  -d '{"query":"neural search","lang":"en","k_bm25":10,"k_knn":10}'
```

Scraper Service

The Scraper fetches and normalizes news articles from various external sources. It's profile-driven and can forward articles to the API.

1. Configure Environment: Create your local .env file for the Scraper service from its template.

cp scraper/.env.example scraper/.env

2. Build & Start Service:

docker compose up --build -d scraper

3. Set API Ingestion Variables (in scraper/.env):

API_INGEST_URL=http://api:8000/v1/ingest/articles
INGEST_TOKEN=<your-token>
INGEST_BATCH_SIZE=50

4. Trigger a test scrape:

curl -X POST http://localhost:9001/scrape \
  -H "Content-Type: application/json" \
  -d '{"sources": ["verify_sy"], "limit": 5, "send_to_api": false}'

4. Daily Developer Workflow¶

Once the platform is set up, your daily workflow will be much simpler.

Daily Workflow

Pull Latest Changes:
```
git pull origin main
```
Start Services: Start all services in the background. A rebuild is only needed if a Dockerfile or dependencies change.
```
docker compose up -d
```
Run Local Tests: Before committing, run the local test suites for the service you are working on.
```
# Example for the scraper service
docker compose exec scraper pytest
```
View Logs: Tail the logs for a specific service to debug issues.
```
docker compose logs -f api
```
Stop Services: When you're done for the day, stop all running services.
```
docker compose down
```