# Jana Backend Configuration Reference
**Date:** 2026-01-22
**Purpose:** Document the Jana backend Docker environment for MCP server integration
---
## Overview
The Jana MCP Server will connect to the Jana backend running locally in Docker. This document captures the networking configuration, endpoints, and authentication details needed for integration.
---
## Docker Services Architecture
```mermaid
graph TB
subgraph External [Host Machine Access]
Host["localhost / 127.0.0.1"]
end
subgraph DockerNetwork [Docker Default Bridge Network]
Web["web - Django API - port 8000"]
PgBouncer["pgbouncer - Connection Pool"]
DB["db - PostgreSQL PostGIS"]
Redis["redis - Cache and Broker"]
Celery["celery - Background Workers"]
CeleryBeat["celery-beat - Scheduler"]
Flower["flower - Celery Monitoring"]
PgAdmin["pgadmin - DB Admin UI"]
end
Host -->|"port 8000"| Web
Host -->|"port 5432"| DB
Host -->|"port 6432"| PgBouncer
Host -->|"port 6379"| Redis
Host -->|"port 5555"| Flower
Host -->|"port 5050"| PgAdmin
Web --> PgBouncer
Web --> Redis
Celery --> PgBouncer
Celery --> Redis
CeleryBeat --> Redis
PgBouncer --> DB
Flower --> Redis
```
---
## Port Mapping
### External Ports (Access from Host)
| Service | Container Port | Host Port | URL from Host |
|---------|----------------|-----------|---------------|
| **web** (Django API) | 8000 | 8000 | `http://localhost:8000` |
| **db** (PostgreSQL/PostGIS) | 5432 | 5432 | `localhost:5432` |
| **pgbouncer** (Connection Pool) | 5432 | 6432 | `localhost:6432` |
| **redis** | 6379 | 6379 | `localhost:6379` |
| **flower** (Celery UI) | 5555 | 5555 | `http://localhost:5555` |
| **pgadmin** | 80 | 5050 | `http://localhost:5050` |
### MCP Server Connection
The MCP server will run **outside Docker** on the host machine and connect to:
```
API Base URL: http://localhost:8000
```
---
## Internal Docker Networking
Services within Docker communicate using the **default bridge network** via service names:
| From Service | To Service | Connection String |
|--------------|------------|-------------------|
| web | pgbouncer | `postgres://postgres:postgres@pgbouncer:5432/fr_data_service` |
| web | redis | `redis://redis:6379/0` |
| celery | pgbouncer | `postgres://postgres:postgres@pgbouncer:5432/fr_data_service` |
| celery | redis (broker) | `redis://redis:6379/0` |
| celery | redis (results) | `redis://redis:6379/1` |
| pgbouncer | db | `db:5432` |
| flower | redis | `redis://redis:6379/0` |
**Note:** The MCP server does NOT use these internal URLs. It connects via `localhost` ports exposed to the host.
---
## API Endpoints
### Base URLs
| Environment | Base URL |
|-------------|----------|
| Local Docker | `http://localhost:8000` |
| Production | TBD |
### Endpoint Catalog
| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/health/` | GET | No | Basic health check |
| `/api/auth/login/` | POST | No | Get authentication token |
| `/api/auth/logout/` | POST | Yes | Invalidate token |
| `/api/v1/esg/` | - | Yes | Unified ESG data API |
| `/api/v1/esg/data/` | GET | Yes | Cross-source data queries |
| `/api/v1/esg/correlations/` | GET | Yes | Correlation analysis |
| `/api/v1/esg/trends/` | GET | Yes | Trend analysis |
| `/api/v1/esg/aggregations/` | GET | Yes | Temporal aggregations |
| `/api/v1/esg/quality/` | GET | Yes | Data quality insights |
| `/api/v1/esg/health/` | GET | Yes | ESG service health |
| `/api/v1/management/` | - | Yes | Job management API |
| `/api/v1/management/jobs/` | GET/POST | Yes | List/create jobs |
| `/api/v1/management/executions/` | GET | Yes | List executions |
| `/api/v1/management/health/` | GET | Yes | Management health |
| `/api/v1/data-sources/openaq/` | - | Varies | OpenAQ-specific endpoints |
| `/api/v1/data-sources/climatetrace/` | - | Yes | Climate TRACE endpoints |
| `/api/v1/data-sources/edgar/` | - | Yes | EDGAR endpoints |
| `/api/docs/` | GET | No | Swagger UI documentation |
| `/api/redoc/` | GET | No | ReDoc documentation |
| `/api/schema/` | GET | No | OpenAPI schema (JSON/YAML) |
---
## Authentication
### Token-Based Authentication
The API uses **Django REST Framework Token Authentication**.
#### Obtaining a Token
```bash
curl -X POST http://localhost:8000/api/auth/login/ \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "admin"}'
```
**Response:**
```json
{
"token": "abc123def456..."
}
```
#### Using the Token
Include the token in the `Authorization` header:
```bash
curl http://localhost:8000/api/v1/esg/data/ \
-H "Authorization: Token abc123def456..."
```
#### Default Development Credentials
| Username | Password | Notes |
|----------|----------|-------|
| admin | admin | Default superuser |
---
## Rate Limits
| User Type | Rate Limit |
|-----------|------------|
| Anonymous | 100 requests/hour |
| Authenticated | 1000 requests/hour |
**Note:** Rate limits are per-user and reset hourly.
---
## Database Configuration
### PostgreSQL with PostGIS
| Setting | Value |
|---------|-------|
| Image | `postgis/postgis:16-3.4` |
| Database | `fr_data_service` |
| User | `postgres` |
| Password | `postgres` |
| Max Connections | 400 |
| Shared Buffers | 3GB |
### PgBouncer (Connection Pooling)
| Setting | Value |
|---------|-------|
| Pool Mode | transaction |
| Max Client Connections | 1000 |
| Default Pool Size | 100 |
---
## Redis Configuration
| Setting | Value |
|---------|-------|
| Image | `redis:7-alpine` |
| Database 0 | Celery broker |
| Database 1 | Celery results |
| Memory Limit | 512MB |
---
## MCP Server Integration Notes
### Connection Configuration
The MCP server should be configured with:
```python
# MCP Server Configuration
JANA_BACKEND_URL = "http://localhost:8000"
JANA_AUTH_ENDPOINT = "/api/auth/login/"
```
### Authentication Flow
```mermaid
sequenceDiagram
participant MCP as MCP Server
participant Jana as Jana Backend
Note over MCP: On startup or token expiry
MCP->>Jana: POST /api/auth/login/
Jana-->>MCP: Token response
MCP->>MCP: Store token
Note over MCP: On each API call
MCP->>Jana: GET /api/v1/esg/data/ + Auth header
Jana-->>MCP: Data response
```
### Using eko-client-python
The MCP server should use `eko-client-python` for API access:
```python
from eko_client import EkoUserClient
client = EkoUserClient(
base_url="http://localhost:8000",
username="admin",
password="admin"
)
# Client handles token management automatically
data = client.get_data(
sources=["openaq", "climatetrace"],
location_point=[-74.0, 40.7],
radius_km=25
)
```
---
## Docker Compose Files
| File | Purpose |
|------|---------|
| `docker-compose.yml` | Main configuration |
| `docker-compose.override.yml` | Local dev overrides (Apple Silicon) |
| `docker-compose.cloud-db.yml` | Cloud database configuration |
| `docker-compose.eks.yml` | EKS deployment configuration |
### Starting the Stack
```bash
cd /Users/willardmechem/Projects/repos/Jana
docker compose up -d
```
### Verifying Health
```bash
# Check all services
docker compose ps
# Check API health
curl http://localhost:8000/health/
# Check management health (requires auth)
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login/ \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"admin"}' | jq -r '.token')
curl http://localhost:8000/api/v1/management/health/ \
-H "Authorization: Token $TOKEN"
```
---
## Related Documents
- [API_ENDPOINTS.md](/Users/willardmechem/Projects/repos/Jana/docs/architecture_docs/API_ENDPOINTS.md) - Full endpoint documentation
- [API_ARCHITECTURE.md](/Users/willardmechem/Projects/repos/Jana/docs/architecture_docs/API_ARCHITECTURE.md) - API design
- [eko-client-python README](/Users/willardmechem/Projects/repos/Jana/eko-client-python/README.md) - Client library docs
---
## Changelog
| Date | Change |
|------|--------|
| 2026-01-22 | Initial documentation created |
