ZeebeeAI Deployment Guide

Overview

This document provides guidelines for deploying the ZeebeeAI Chat SDK Platform to production environments. The platform is built with Flask (Python) and integrates with multiple LLM providers.

System Requirements

• Python 3.11+
• PostgreSQL database
• Redis (optional, for caching and queue management)
• Node.js (optional, for front-end development)

Environment Variables

The following environment variables must be configured:

Required

• DATABASE_URL: PostgreSQL connection string
• SESSION_SECRET: Secret key for session management
• OPENAI_API_KEY: OpenAI API key for accessing OpenAI models

Optional (Provider-specific)

• ANTHROPIC_API_KEY: Anthropic API key for Claude models
• GOOGLE_API_KEY: Google API key for Gemini models
• MISTRAL_API_KEY: Mistral API key for Mistral models

Optional (Analytics)

• LANGFUSE_PUBLIC_KEY: Langfuse public key for observability
• LANGFUSE_SECRET_KEY: Langfuse secret key for observability
• LANGFUSE_HOST: Langfuse host (defaults to Langfuse Cloud)

Database Setup

1. Create a PostgreSQL database:

   createdb zeebeeai

2. Set the DATABASE_URL environment variable:

   export DATABASE_URL="postgresql://username:password@localhost:5432/zeebeeai"

3. Run database migrations:

   python run_migrations.py

4. Seed subscription plans (if needed):

   python seed_subscription_plans.py

Deployment Options

Docker Deployment

1. Build the Docker image:

   docker build -t zeebeeai:latest .

2. Run the container:

   docker run -p 5000:5000 --env-file .env zeebeeai:latest

Traditional Deployment

1. Clone the repository:

   git clone https://github.com/yourusername/zeebeeai.git
   cd zeebeeai

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Start the server:

   gunicorn --bind 0.0.0.0:5000 --workers 4 main:app

Scaling Considerations

Horizontal Scaling

The application can be horizontally scaled by running multiple instances behind a load balancer. Ensure that:

1. All instances connect to the same database
2. Session management is configured for distributed deployment
3. Caching strategy is appropriate for multiple instances

Vertical Scaling

For increased performance on a single instance:

1. Increase the number of Gunicorn workers (2-4× the number of CPU cores)
2. Tune the PostgreSQL database for performance
3. Consider using PyPy or similar for improved Python performance

Monitoring & Maintenance

Health Checks

The application exposes a health check endpoint at /api/health which should return a 200 status code and basic information about the service.

Logging

Logs are output to stdout/stderr and can be captured by container orchestration platforms or log aggregation tools.

Backup Strategy

1. Regular database backups should be scheduled
2. User-generated content and conversation history should be included in backups
3. API keys and secrets should be managed separately

Security Considerations

1. Always use HTTPS in production
2. Implement rate limiting for API endpoints
3. Regularly audit user permissions and API key usage
4. Monitor for unusual activity patterns

Update Process

1. Always back up the database before updating
2. Run migrations after code updates
3. Use rolling updates to minimize downtime
4. Have a rollback plan for failed deployments

Support & Troubleshooting

For issues, refer to the logs first. Common issues include:

1. Database connection errors (check DATABASE_URL and network connectivity)
2. API key validation failures (verify provider API keys)
3. Memory issues (monitor resource usage)

Contact support@zeebeeai.com for additional assistance.