Skip to content

Docker Deployment Guide

This guide shows you how to deploy Champa Intelligence using our pre-built Docker image. No compilation or building required - just configure and run.

Architecture Overview

Champa Intelligence runs as a multi-container stack:

graph TB
    subgraph "Docker Host"
        subgraph "Nginx :80/:443"
            N1[Application Proxy]
            N2[Documentation<br/>docs.champa-bpmn.com]
        end

        subgraph "Application Stack"
            APP[Champa Intelligence<br/>:8088]
            SDB[(System Database<br/>PostgreSQL :5433)]
            REDIS[Redis Cache<br/>:6379]
        end

        EXT[(Your Camunda DB<br/>External)]
    end

    Internet --> N1
    Internet --> N2
    N1 --> APP
    APP --> SDB
    APP --> REDIS
    APP -.Read Only.-> EXT

    style APP fill:#4CAF50
    style EXT fill:#FF9800
Hold "Alt" / "Option" to enable pan & zoom

Components:

  • champa-intelligence: Main application (pre-built image)
  • champa-system-db: PostgreSQL for users, sessions, audit logs
  • champa-redis: High-performance cache
  • nginx: Reverse proxy and documentation server

Prerequisites

  • Docker Engine (v20.10+) and Docker Compose (v2.0+)
  • Access to your existing Camunda 7 PostgreSQL database
  • Google Gemini API key (for AI features)
  • A domain name with DNS configured (for production)

Quick Start

1. Download Deployment Package

Download the deployment package from Champa Intelligence:

# Extract the package
tar -xzf champa-intelligence-deployment.tar.gz
cd champa-intelligence-deployment

Package contents: 

champa-intelligence-deployment/
├── docker-compose.yml          # Main orchestration file
├── .env.example                # Configuration template
├── nginx/                      # Nginx configuration
│   ├── nginx.conf
│   └── docs.conf
└── README.md

2. Load Docker Image

Load the pre-built Champa Intelligence image:

docker load -i champa-intelligence-latest.tar

Verify the image is loaded:

docker images | grep champa-intelligence

Expected output: 

champa-intelligence    latest    abc123def456    2 days ago    450MB

3. Configure Environment

Create your configuration file:

cp .env.example .env
nano .env

Required Configuration:

# ============================================================
# Your Camunda Database (Read-Only Access)
# ============================================================
DB_HOST=10.0.1.50                    # Your Camunda DB IP/hostname
DB_PORT=5432
DB_NAME=camunda
DB_USER=camunda_readonly             # Recommended: read-only user
DB_PASSWORD=your_camunda_db_password

# ============================================================
# System Database (Auto-created)
# ============================================================
SYSTEM_DB_PASSWORD=generate_strong_password_here

# ============================================================
# Redis Cache (Auto-created)
# ============================================================
REDIS_PASSWORD=another_strong_password

# ============================================================
# Security Keys (CRITICAL - Generate Unique Values!)
# ============================================================
JWT_SECRET=your_jwt_secret_32_chars_minimum
APP_SECRET_KEY=your_flask_secret_32_chars_minimum

# ============================================================
# AI Configuration
# ============================================================
GOOGLE_API_KEY=your_google_gemini_api_key

# ============================================================
# Camunda REST API (Optional)
# ============================================================
CAMUNDA_API_URL=http://your-camunda:8080/engine-rest
CAMUNDA_API_USER=demo
CAMUNDA_API_PASSWORD=demo

# ============================================================
# Performance Tuning (Optional)
# ============================================================
GUNICORN_WORKERS=4    # Recommended: (2 × CPU cores) + 1
GUNICORN_THREADS=2
GUNICORN_TIMEOUT=300

Generate secure secrets: 

# Generate JWT secret
openssl rand -hex 32

# Generate Flask secret
openssl rand -hex 32

4. Start the Stack

docker-compose up -d

What happens: 1. System database starts and initializes 2. Redis cache starts 3. Application starts and connects to databases 4. Nginx starts and proxies requests

Check status: 

docker-compose ps

Expected output: 

NAME                  STATUS              PORTS
champa-intelligence   Up 30 seconds       0.0.0.0:8088->8088/tcp
champa-system-db      Up 35 seconds       0.0.0.0:5433->5432/tcp
champa-redis          Up 35 seconds       6379/tcp
nginx                 Up 28 seconds       0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp

5. Initialize Database

First-time setup only - create admin user and default roles:

docker exec champa-intelligence python -c "from db import init_auth_db; init_auth_db()"

Expected output: 

✓ Creating authentication schema...
✓ Creating default roles...
✓ Creating default permissions...
✓ Creating admin user...
✓ Database initialized successfully!

6. Access Application

Development/Testing: - URL: http://your-server-ip:8088 - Username: admin - Password: admin123

Production (with Nginx): - URL: https://your-domain.com - Documentation: https://docs.your-domain.com

Security Warning

Change the default admin password immediately after first login!

Service Management

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f champa-intelligence

# Last 100 lines
docker-compose logs --tail=100 champa-intelligence

Stop Services

docker-compose stop

Start Services

docker-compose start

Restart Application

docker-compose restart champa-intelligence

Complete Shutdown

# Stop and remove containers (data preserved)
docker-compose down

# Stop, remove containers AND delete all data
docker-compose down -v

SSL/TLS Configuration

# Install certbot
apt-get install certbot python3-certbot-nginx

# Get certificate
certbot --nginx -d your-domain.com -d docs.your-domain.com

# Certbot will automatically update nginx configuration

Certificates auto-renew via cron job.

Option 2: Custom Certificates

Place your certificates in nginx/ssl/:

nginx/ssl/
├── your-domain.crt
├── your-domain.key
└── ca-bundle.crt

Update nginx/nginx.conf:

ssl_certificate /etc/nginx/ssl/your-domain.crt;
ssl_certificate_key /etc/nginx/ssl/your-domain.key;

Restart nginx: 

docker-compose restart nginx

Upgrading

Step 1: Download New Version

Receive new image from Champa Intelligence:

docker load -i champa-intelligence-v2.0.0.tar

Step 2: Update Configuration

Check for new environment variables:

# Compare your config with new template
diff .env .env.example

Add any new required variables to .env.

Step 3: Restart with New Image

# Stop current version
docker-compose down

# Start with new image
docker-compose up -d

Step 4: Run Migrations (if needed)

Check release notes. If database migrations are required:

docker exec champa-intelligence python -c "from db import run_migrations; run_migrations()"

Troubleshooting

Cannot Connect to Camunda Database

Check connectivity from container:

docker exec champa-intelligence python -c "
import psycopg2
conn = psycopg2.connect(
    host='YOUR_DB_HOST',
    port=5432,
    dbname='camunda',
    user='YOUR_USER',
    password='YOUR_PASSWORD'
)
print('✓ Connection successful')
conn.close()
"

Common fixes: - Verify DB_HOST is reachable from Docker host - Check firewall rules allow port 5432 - Ensure database user has SELECT permissions - If using Docker network, use container name instead of localhost

Application Won't Start

View detailed logs:

docker-compose logs champa-intelligence

Common issues:

  1. Port 8088 already in use: 

    Error: Bind for 0.0.0.0:8088 failed: port is already allocated
    Stop the conflicting service or change port in docker-compose.yml: 
    ports:
  - "8089:8088"  # Use different external port

  2. Missing environment variables: 

    KeyError: 'DB_PASSWORD'
    Verify all required variables in .env file.

  3. Redis connection failed: Check Redis is running: 

    docker-compose ps champa-redis

Slow Performance

Check resource usage:

docker stats

Adjust workers:

Edit .env: 

# For 8-core CPU
GUNICORN_WORKERS=17  # (2 × 8) + 1
GUNICORN_THREADS=4

Restart: 

docker-compose restart champa-intelligence

Health Check

# Application health
curl http://localhost:8088/health/ping

# Database connectivity
curl http://localhost:8088/health/db

# Full system check
curl http://localhost:8088/health/api/full

Expected response: 

{
  "status": "OK",
  "timestamp": "2025-10-30T12:34:56",
  "version": "2.0.0"
}

Backup & Recovery

Backup System Database

# Create backup
docker exec champa-system-db pg_dump \
  -U champa_user champa_system \
  > backup-$(date +%Y%m%d-%H%M%S).sql

# Compress
gzip backup-*.sql

Restore from Backup

# Stop application
docker-compose stop champa-intelligence

# Restore database
gunzip -c backup-20251030-120000.sql.gz | \
  docker exec -i champa-system-db psql \
  -U champa_user champa_system

# Restart application
docker-compose start champa-intelligence

Backup Redis Cache

# Trigger Redis save
docker exec champa-redis redis-cli -a YOUR_REDIS_PASSWORD SAVE

# Copy RDB file
docker cp champa-redis:/data/dump.rdb ./redis-backup-$(date +%Y%m%d).rdb

Production Best Practices

1. Security Hardening

  • ✅ Use strong, unique passwords for all services
  • ✅ Change default admin password immediately
  • ✅ Run behind reverse proxy with SSL/TLS
  • ✅ Create read-only database user for Camunda DB
  • ✅ Restrict network access (firewall rules)
  • ✅ Regular security updates

2. Monitoring

Set up health checks in your monitoring system:

# Application liveness
curl -f http://localhost:8088/health/ping || exit 1

# Database connectivity
curl -f http://localhost:8088/health/db || exit 1

3. Log Management

Forward logs to centralized logging:

# Add to docker-compose.yml
services:
  champa-intelligence:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

4. Resource Limits

Prevent resource exhaustion:

# Add to docker-compose.yml
services:
  champa-intelligence:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '1.0'
          memory: 1G

5. Automated Backups

Create backup cron job:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * cd /path/to/champa && ./backup.sh

Configuration Reference

Essential Environment Variables

Variable Required Description Example
DB_HOST ✓ Camunda database host 10.0.1.50
DB_PORT ✓ Camunda database port 5432
DB_NAME ✓ Camunda database name camunda
DB_USER ✓ Database username camunda_user
DB_PASSWORD ✓ Database password secure_pass
SYSTEM_DB_PASSWORD ✓ System DB password another_pass
REDIS_PASSWORD ✓ Redis password redis_pass
JWT_SECRET ✓ JWT signing key (32+ chars) random_string
APP_SECRET_KEY ✓ Flask secret (32+ chars) random_string
GOOGLE_API_KEY ✓ Gemini API key AIza...

Optional Environment Variables

Variable Default Description
GUNICORN_WORKERS Auto Worker processes
GUNICORN_THREADS 2 Threads per worker
GUNICORN_TIMEOUT 300 Request timeout (seconds)
LOG_LEVEL INFO Logging level
CAMUNDA_API_URL - Camunda REST API endpoint

Port Mappings

Service Internal Port External Port Protocol
Application 8088 8088 HTTP
System DB 5432 5433 PostgreSQL
Redis 6379 - Redis
Nginx 80/443 80/443 HTTP/HTTPS

Getting Help

Check Logs First

# Application logs
docker-compose logs champa-intelligence | tail -100

# All services
docker-compose logs --tail=50

Common Log Patterns

Success: 

✓ Database connection established
✓ Redis connection established
✓ Application started on port 8088

Errors: 

❌ Could not connect to database
❌ Redis connection refused
❌ Invalid JWT secret format

Support

Next Steps