Getting Started¶

Welcome to Champa Intelligence! This section provides everything you need to get the platform installed, configured, and running in your environment.

Whether you prefer a quick setup for evaluation, a Docker-based deployment, or an enterprise Kubernetes cluster, these documents will walk you through the process.

Recommended Path¶

For the best experience, we recommend following these steps in order:

Review the Prerequisites to ensure your environment is ready.
Follow the Quick Start Guide for the fastest way to get a running instance using Docker.
Refer to the Installation Guide for more detailed, production-focused instructions.
Use the Configuration Guide and Environment Variables Reference to customize the platform for your specific Camunda setup.
For enterprise deployments, review the Kubernetes Deployment Guide.

Quick Start Guide

Get a fully functional instance up and running in under 15 minutes using our Docker Compose setup. Perfect for evaluation and development.
Installation Guide

Follow detailed, step-by-step instructions for both Docker-based production deployments and manual installations.
Configuration Guide

Dive deep into the config.py and .env files to fine-tune application behavior, from database connections to AI settings.
Environment Variables Reference

A complete reference for all environment variables used to configure and secure the application, with examples for different environments.
Docker Deployment

Production-ready Docker deployment guide with Docker Compose for single-server setups.
Kubernetes Deployment

Enterprise-grade high availability deployment on Kubernetes with automatic failover and horizontal scaling.

Deployment Options¶

Quick Comparison¶

Method	Time to Deploy	Complexity	HA Support	Best For
Quick Start	1 hour	Low	No	Development, Testing
Docker Compose	2 hours	Medium	Manual	Small Production
Kubernetes	4-6 hours	High	Automatic	Enterprise, Cloud

Docker Compose (Recommended for Most Users)¶

Perfect for: - Single server deployments - Small to medium teams - Development and staging environments - Quick production setups

Features: - All-in-one deployment - Built-in PostgreSQL and Redis - Easy updates and rollbacks - Minimal infrastructure requirements

Quick command:

docker-compose -f docker-compose.server.yml up -d

Read Docker Deployment Guide →

Kubernetes (Enterprise)¶

Perfect for: - Large organizations - Multi-region deployments - High availability requirements - Cloud-native infrastructures

Features: - Automatic failover (Patroni PostgreSQL, Redis Sentinel) - Horizontal pod autoscaling - Rolling updates with zero downtime - Advanced monitoring and observability - Multi-node redundancy

Quick command:

kubectl apply -f k8s/

Read Kubernetes Deployment Guide →

Prerequisites¶

Before you begin, please ensure you have the following:

Technical Requirements¶

For Docker Deployment¶

Docker & Docker Compose (Recommended): The easiest and most reliable way to run the application.
- Docker Engine 20.10+
- Docker Compose 2.0+
- 4GB+ RAM
- 2+ CPU cores
- 20GB+ disk space

For Kubernetes Deployment¶

Kubernetes Cluster: Version 1.24+
- 3+ worker nodes (recommended)
- 6GB+ RAM total
- 4+ CPU cores total
- 50GB+ storage for persistent volumes
kubectl: Configured and connected to your cluster
Helm: (optional) For easier ingress controller installation

For Manual Installation¶

Python: 3.10+
Node.js: 16+ and npm
PostgreSQL: 14+
Redis: 6+
Git: For cloning the repository

System Access¶

Camunda Database Access: Read-only credentials for your Camunda 7 PostgreSQL database.
Google Gemini API Key: Required to enable the AI-Powered Analysis features. You can obtain a key from the Google AI Studio.
Network Access: Ensure the deployment environment can reach your Camunda database and REST API endpoints.

Read-Only is Sufficient

Champa Intelligence only requires read-only access to your Replica of Camunda database, ensuring it can never interfere with your running processes. The application uses its own separate database for storing user accounts and session data.

Architecture Overview¶

Docker Compose Architecture¶

graph LR
    USER[User Browser] --> NGINX[Nginx :443]
    NGINX --> APP[Champa App :8088]
    APP --> SYSDB[(System DB :5433)]
    APP --> REDIS[(Redis :6379)]
    APP --> CAMDB[(Camunda DB External)]

Hold "Alt" / "Option" to enable pan & zoom

Components:

Nginx reverse proxy (optional, for SSL)
Champa Intelligence Flask application
System PostgreSQL database (auth, sessions)
Redis cache
External Camunda database (read-only)

Kubernetes Architecture¶

graph TB
    USER[User Browser]

    subgraph "Kubernetes Cluster"
        ING[Ingress Controller]
        APP1[App Pod 1]
        APP2[App Pod 2]

        subgraph "Database HA"
            MASTER[Patroni Master]
            REPLICA[Patroni Replica]
            ETCD[etcd]
        end

        subgraph "Cache HA"
            RMASTER[Redis Master]
            RREPLICA[Redis Replica]
            SENT[Sentinel x3]
        end
    end

    CAMDB[(Camunda DB External)]

    USER --> ING
    ING --> APP1
    ING --> APP2
    APP1 --> MASTER
    APP2 --> MASTER
    APP1 --> RMASTER
    APP2 --> RMASTER
    MASTER -.-> REPLICA
    MASTER --> ETCD
    REPLICA --> ETCD
    RMASTER -.-> RREPLICA
    SENT -.-> RMASTER
    SENT -.-> RREPLICA
    APP1 --> CAMDB
    APP2 --> CAMDB

Hold "Alt" / "Option" to enable pan & zoom

Components:

Ingress controller for load balancing
Multiple application pods
Patroni PostgreSQL cluster (automatic failover)
Redis with Sentinel (automatic failover)
etcd for distributed coordination
External Camunda database (read-only)

Installation Paths¶

Path 1: Quick Evaluation (1 hour)¶

For trying out Champa Intelligence quickly:

Install Docker Desktop
Clone repository
Run docker-compose up -d
Access at http://localhost:8088

Follow Quick Start Guide →

Path 2: Production Single Server (2 hours)¶

For production deployment on a single server:

Install Docker and Docker Compose
Configure environment variables
Build frontend assets
Deploy with docker-compose.server.yml
Configure Nginx for SSL

Follow Docker Deployment Guide →

Path 3: Enterprise Kubernetes (4-6 hours)¶

For high availability production deployment:

Prepare Kubernetes cluster
Configure secrets and ConfigMaps
Deploy infrastructure (Patroni, Redis Sentinel, etcd)
Deploy application pods
Configure ingress and monitoring

Follow Kubernetes Deployment Guide →

Quick Decision Guide¶

Choose Docker Compose if:

You have a single server or VM
You need quick deployment
Your team is small to medium
You're comfortable with manual failover
You want simple maintenance

Choose Kubernetes if:

You need high availability
You have multiple servers/nodes
You want automatic failover
You need horizontal scaling
You're running in cloud (AWS, GCP, Azure)
Your team has Kubernetes experience

Next Steps¶

Once you have a running instance, you'll be ready to:

Explore the Features to learn what you can do with the platform.
Set up Users and Roles to provide access to your team.
Integrate with Prometheus for enterprise-grade monitoring.
Configure Backup Procedures for data protection.

Getting Help¶

Documentation¶

Installation Guide - Detailed setup instructions
Configuration Guide - Customize your deployment
Troubleshooting - Common issues and solutions
API Reference - API documentation

Professional Support¶

For enterprise support, custom integrations, or consulting services, contact us at info@champa-bpmn.com.