Production Setup

Best practices for deploying Epochly in production environments.

Installation with Doctor Check

# Install Epochly
pip install epochly
# Run system compatibility check
epochly doctor

The epochly doctor command verifies:

• Python version compatibility
• Required dependencies
• System resources (CPU, memory)
• Optional features availability

System Requirements

Conservative Production Settings

Start with conservative settings for production:

export EPOCHLY_LEVEL=2
export EPOCHLY_MODE=conservative
export EPOCHLY_MAX_WORKERS=4
export EPOCHLY_LOG_LEVEL=WARNING

Configuration File (epochly.toml)

Create epochly.toml in your project root:

[epochly]
level = 2
mode = "conservative"
max_workers = 8
[epochly.logging]
level = "WARNING"
file = "/var/log/epochly.log"
[epochly.monitoring]
prometheus_enabled = true
prometheus_port = 9090
[epochly.jit]
hot_path_threshold = 1000
cache_enabled = true

Level Selection Guidelines

Level 2 (Recommended)

export EPOCHLY_LEVEL=2
export EPOCHLY_MODE=conservative

Benefits:

• JIT compilation for hot code paths
• Threading optimizations
• Minimal risk profile
• No license required

Activation Methods

1. CLI Runner

# Simple usage
epochly app.py
# With configuration
epochly run --level 2 --mode conservative app.py
# With arguments
epochly app.py arg1 arg2 --option value

2. sitecustomize (Recommended for Production)

epochly sitecustomize install
export EPOCHLY_AUTO_ENABLE=1
export EPOCHLY_MODE=conservative
python your_app.py

3. Programmatic

import epochly
epochly.configure(
    enhancement_level=2,
    mode='conservative',
    max_workers=8
)
# Your application code

Resource Management

CPU Configuration

import epochly
import os
# Match CPU cores
cpu_count = os.cpu_count() or 4
epochly.configure(
    max_workers=cpu_count,
    cpu_affinity=True  # Pin workers to specific cores
)

Memory Limits

# Set memory limits
export EPOCHLY_MEMORY_SHARED_SIZE=67108864  # 64MB
export EPOCHLY_MEMORY_POOL_TYPE=shared

Prometheus Monitoring

import epochly
# Enable metrics export
epochly.configure(
    prometheus_enabled=True,
    prometheus_port=9090
)
# Check status
status = epochly.get_status()
metrics = epochly.get_metrics()

High Availability

Graceful Degradation

Epochly automatically degrades gracefully:

1. Monitors for errors and performance issues
2. Rolls back to lower enhancement level if problems detected
3. Logs degradation events
4. Recovers automatically when stable

Horizontal Scaling

• Each process has independent Epochly state
• No shared state between workers
• Safe for multi-instance deployments
• Works with load balancers

Logging Configuration

import epochly
epochly.configure(
    log_level='WARNING',  # Reduce verbosity
    log_file='/var/log/epochly.log',
    log_format='json'  # Structured logging
)

Security Best Practices

1. License Keys: Use environment variables, never hardcode
2. Logging: Avoid logging sensitive data
3. Permissions: Run with minimal required permissions
4. Network: Epochly makes no external network calls (except license validation)

Health Check Endpoint

from flask import Flask, jsonify
import epochly
app = Flask(__name__)
@app.route('/health/epochly')
def epochly_health():
    status = epochly.get_status()
    return jsonify({
        'healthy': status['initialized'],
        'level': status['enhancement_level'],
        'mode': status['mode'],
        'workers': status.get('active_workers', 0)
    })

Pre-Deployment Checklist

Before deploying Epochly to production:

• [ ] Installation Verified: Run epochly doctor to verify system compatibility
• [ ] Configuration Set: Environment variables or epochly.toml configured
• [ ] Conservative Settings: Start with EPOCHLY_LEVEL=2 and EPOCHLY_MODE=conservative
• [ ] Resource Limits: CPU and memory limits configured appropriately
• [ ] Monitoring Enabled: Prometheus or metrics collection configured
• [ ] Logging Configured: Log level set to WARNING or ERROR for production
• [ ] Health Checks: Health check endpoint implemented and tested
• [ ] Emergency Controls: Document emergency disable procedures
• [ ] Staging Tested: Tested in staging environment with production-like load
• [ ] Rollback Plan: Emergency disable and rollback procedures documented
• [ ] License Validated: Pro/Enterprise license key verified (if using Level 4)
• [ ] Security Review: License keys in environment variables, not hardcoded

Post-Deployment Checklist

After deploying Epochly:

• [ ] Verify Initialization: Check /health/epochly endpoint returns healthy status
• [ ] Monitor Metrics: Watch CPU, memory, and Epochly-specific metrics
• [ ] Check Logs: Review logs for any errors or warnings
• [ ] Validate Performance: Compare baseline performance metrics
• [ ] Test Emergency Disable: Verify EPOCHLY_EMERGENCY_DISABLE=1 works
• [ ] Monitor for 24 hours: Watch for memory leaks or degradation
• [ ] Document Configuration: Record all settings and performance baselines
• [ ] Alert Configuration: Set up alerts for high error rates or degradation

Troubleshooting Production Issues

High Memory Usage

# Reduce max workers
export EPOCHLY_MAX_WORKERS=2
# Limit shared memory pool
export EPOCHLY_MEMORY_SHARED_SIZE=33554432  # 32MB
# Restart application

Performance Degradation

# Drop to lower level
export EPOCHLY_LEVEL=1
# Or switch to monitoring only
export EPOCHLY_MODE=monitoring
# Restart and monitor

Unexpected Errors

# Enable debug logging temporarily
export EPOCHLY_LOG_LEVEL=DEBUG
# Check logs
tail -f /var/log/epochly.log
# Disable if needed
export EPOCHLY_EMERGENCY_DISABLE=1

Related Documentation

• Docker Deployment
• Emergency Controls
• Monitoring Integration
• Configuration API
• Security Considerations