Deployment Guide

Deploy Nuraan for your humanitarian operations

Prerequisites

System Requirements

• CPU: 4+ cores (8 recommended)
• RAM: 8GB minimum (16GB recommended)
• Storage: 50GB SSD (more for data)
• OS: Ubuntu 22.04 LTS or similar

Software Dependencies

• Docker: 24.0+ with Compose v2
• Git: For cloning repository
• Domain: For HTTPS (optional)
• SSL: Automated via Caddy

Quick Start

1 Clone Repository

git clone https://github.com/nuraan-ai/nuraan-prototype.git
cd nuraan-prototype

2 Configure Environment

# Create authentication config
cat > .env.login << 'EOF'
NURAAN_LOGIN_USERS=admin:YourSecurePassword123!
NURAAN_AUTH_SECRET=$(openssl rand -hex 32)
EOF

# For production with HTTPS
cp Caddyfile.example Caddyfile
# Edit Caddyfile to set your domain

3 Launch Services

# Development (local)
docker-compose up -d

# Production (with HTTPS)
docker-compose -f docker-compose.prod.yml up -d

# Check status
docker-compose ps

4 Initialize Database

# Option A: Load ADM3 boundaries (544 areas - faster, lower detail)
docker-compose exec -T api python /app/load_dhaka_adm3.py --wipe

# Option B: Load ADM4 boundaries (RECOMMENDED for production - higher detail)
# First upload geoBoundaries-BGD-ADM4-all.zip to data_and_resources/
docker-compose exec -T api python /app/load_dhaka_adm3.py --adm-level 4 --wipe

# Verify data loaded
docker-compose exec postgres psql -U nuraan -d nuraan   -c "SELECT COUNT(*), level FROM admin_areas GROUP BY level;"

Production Deployment

Automatic HTTPS with Caddy

1. Configure Domain

# Caddyfile
app.your-domain.com {
    # Authentication routes go to Next.js
    handle /api/auth/* {
        reverse_proxy web:3000
    }

    # API routes go to FastAPI
    handle /api/* {
        reverse_proxy api:8000
    }

    # Everything else goes to Next.js
    handle {
        reverse_proxy web:3000
    }
}

2. Deploy with Script

chmod +x deploy-production.sh
./deploy-production.sh

✓ Caddy automatically obtains and renews Let's Encrypt certificates

Security Checklist

Change default passwords in .env.login Generate unique NURAAN_AUTH_SECRET Configure firewall (allow 80, 443, 22 only) Enable automatic security updates Set up monitoring and alerting Configure database backups

Monitoring & Maintenance

Health Monitoring

# Check API health
curl https://app.your-domain.com/api/v1/health

# View container logs
docker-compose logs -f --tail=100

# Monitor resource usage
docker stats

Database Backup

# Backup PostgreSQL
docker-compose exec postgres pg_dump -U nuraan   nuraan | gzip > backup_$(date +%Y%m%d).sql.gz

# Restore from backup
gunzip -c backup_20250101.sql.gz |   docker-compose exec -T postgres psql -U nuraan

Troubleshooting

Container won't start

Check logs for the specific service:

docker-compose logs web
docker-compose logs api

Common issues: port conflicts, missing environment variables, insufficient resources.

Database connection failed

Ensure databases are running:

docker-compose ps postgres clickhouse
docker-compose restart postgres

HTTPS not working

Check Caddy logs and ensure DNS is configured:

docker-compose logs caddy
nslookup app.your-domain.com

Caddy needs ports 80 and 443 open for Let's Encrypt validation.

Need Deployment Assistance?

Our team can help with production deployment, customization, and training.

Contact Support