🚀 Ambrosia Dashboard

---

📋 Table of Contents

• Architecture
• Quick Start
• Configuration
• Development
• Troubleshooting

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Browser / Client                               │
└───────────────┬─────────────────────────────────────────────────────────────┘
                │ HTTP :80
┌───────────────▼─────────────────────────────────────────────────────────────┐
│                         Nginx reverse proxy                                 │
│  /static/ → shared staticfiles volume                                       │
│  /       → ambrosia_dashboard:8000                                          │
└───────────────┬─────────────────────────────────────────────────────────────┘
                │
┌───────────────▼────────────────────────────────────────────────────────────┐
│                   Django / Gunicorn app (container :8000)                  │
│  Dashboard + view modes        Risk charts + chart pages                   │
│  Climate data API              Pathogen concentration API                  │
│  Vocabulary / NUTS / models    User auth + admin                           │
│  Ambra chart assistant         Health endpoint (/status)                   │
└───────┬───────────────┬──────────────────┬─────────────────────────────────┘
        │               │                  │
        │ SQL/PostGIS   │ broker/result    │ HTTPS
        │               │                  │
┌───────▼────────┐ ┌────▼──────────┐ ┌─────▼─────────────────────────────────┐
│ PostgreSQL 16  │ │ Redis 7       │ │ External services                     │
│ + PostGIS      │ │ broker/result │ │ SCiO vocabulary / NUTS / models APIs  │
│ Climate data   │ └────┬──────────┘ │ SCiO pathogen concentration API       │
│ Pathogen data  │      │            │ LLM chat completions endpoint         │
│ Vocabularies   │      │            └───────────────────────────────────────┘
│ Users / admin  │      │
└───────┬────────┘      │ Celery broker/result
        │               │
┌───────▼────────┐ ┌────▼───────────────────────────────────────────────────┐
│ pgAdmin :5050  │ │ Celery worker + embedded beat                          │
│ DB management  │ │ Auto-resumes pending pathogen sync every 5 minutes     │
└────────────────┘ └────────────────────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

• Docker (v20.10+)
• Docker Compose (v2.0+)
• Git

1. Clone the Repository

git clone https://github.com/ambrosia2024/dashboard.git
cd dashboard

2. Configure Environment

cp .env.sample .env

Edit .env with your configuration:

# Django
DJANGO_SECRET_KEY=your-secure-secret-key-here

# Database (PostgreSQL + PostGIS)
POSTGRES_DB=ambrosia
POSTGRES_USER=amb_admin
POSTGRES_PASSWORD=your-secure-db-password
POSTGRES_HOST=ambrosia_postgres
POSTGRES_PORT=5432

# pgAdmin (optional)
PGADMIN_DEFAULT_EMAIL=admin@yourdomain.com
PGADMIN_DEFAULT_PASSWORD=your-secure-password

# Feature Flags
EMAIL_VERIFICATION_ENABLED=false

# External APIs (optional)
SCIO_VOCAB_API_BASE=

# Ambra (Scaleway Serverless API)
SCW_SECRET_KEY=your-scaleway-iam-api-key

⚠️ Security Note: Generate a strong DJANGO_SECRET_KEY using:

python -c "import secrets; print(secrets.token_urlsafe(50))"

3. Launch the Application

docker compose up -d

This will:

• 🐳 Pull and build required Docker images
• 🗄️ Initialize PostgreSQL with PostGIS extensions
• 🔧 Run Django migrations automatically
• 📦 Collect static files
• 🌐 Start Nginx reverse proxy

4. Access the Application

Service	URL	Description
Dashboard	http://localhost/	Main web application
Admin Panel	http://localhost/admin/	Django admin interface
pgAdmin	http://localhost:5050/	Database management (optional)
Health Check	http://localhost/status	Service health endpoint

5. Create Admin User

docker compose exec ambrosia_dashboard python manage.py createsuperuser

---

⚙️ Configuration

Environment Variables

Variable	Required	Default	Description
DJANGO_SECRET_KEY	Yes	-	Django security key
POSTGRES_DB	Yes	ambrosia	Database name
POSTGRES_USER	Yes	amb_admin	Database user
POSTGRES_PASSWORD	Yes	-	Database password
POSTGRES_HOST	Yes	ambrosia_postgres	Database host
POSTGRES_PORT	No	5432	Database port
EMAIL_VERIFICATION_ENABLED	No	false	Enable email verification
SCIO_VOCAB_API_BASE	No	dev.api...	Vocabulary API endpoint
SCW_SECRET_KEY	For Ambra	-	Scaleway IAM API key
SCW_AI_BASE_URL	No	api.scaleway.ai/.../v1	Scaleway Serverless API base URL
SCW_AI_MODEL	No	qwen3.5-397b-a17b	Model used by Ambra
SCW_AI_REASONING_EFFORT	No	none	none skips the model's hidden reasoning pass; raise to low/medium/high for deeper (slower) answers
SCW_AI_MAX_TOKENS	No	1024	Answer length cap
ALLOWED_HOSTS	No	localhost	Comma-separated allowed hosts

Dashboard View Modes

The application supports customizable dashboard layouts:

1. Access Django Admin: http://localhost/admin/
2. Navigate to Lumenix → Dashboard view modes
3. Create modes like "Farmer View", "Policy Advisor View", "Distributor View"
4. Assign charts to each mode via Dashboard view charts

---

🛠️ Development

Local Development (Without Docker)

Use the helper script to create or synchronize the local virtual environment from requirements.txt:

# Recreate .venv from scratch
scripts/sync_env.sh recreate

# Or synchronize an existing .venv exactly to requirements.txt
scripts/sync_env.sh sync

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Setup local PostgreSQL with PostGIS
# Then configure DATABASES in config/settings.py

# Run migrations
python manage.py migrate

# Collect static files
python manage.py collectstatic

# Start development server
python manage.py runserver

Running Tests

docker compose exec ambrosia_dashboard python manage.py test

Database Migrations

# Create migration
docker compose exec ambrosia_dashboard python manage.py makemigrations

# Apply migration
docker compose exec ambrosia_dashboard python manage.py migrate

Vocabulary Synchronization

To sync plant and pathogen vocabularies from SCiO API:

docker compose exec ambrosia_dashboard python manage.py sync_vocabulary plants
docker compose exec ambrosia_dashboard python manage.py sync_vocabulary pathogens

---

🐛 Troubleshooting

Common Issues

Issue: Database connection failed

# Check database health
docker compose ps
docker compose logs ambrosia_postgres

Issue: Static files not loading

# Rebuild and collect static
docker compose down
docker compose up -d --build

Issue: Permission denied on volumes

# Fix volume permissions
docker compose down -v
docker volume prune  # ⚠️ Warning: Deletes all unused volumes
docker compose up -d

Logs

# View all logs
docker compose logs -f

# View specific service
docker compose logs -f ambrosia_dashboard