Documentation

Docker Deployment

Deploying Epochly in containerized environments.

Basic Dockerfile

FROM python:3.12-slim
WORKDIR /app
# Install Epochly
RUN pip install --no-cache-dir epochly
# Copy application
COPY . .
# Configure Epochly
ENV EPOCHLY_LEVEL=2
ENV EPOCHLY_MODE=balanced
ENV EPOCHLY_AUTO_ENABLE=1
CMD ["python", "app.py"]

Transparent Activation with sitecustomize

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir epochly
# Install sitecustomize for transparent activation
RUN epochly sitecustomize install
# Verify installation
RUN epochly sitecustomize validate
COPY . .
ENV EPOCHLY_LEVEL=2
ENV EPOCHLY_MODE=conservative
ENV EPOCHLY_MAX_WORKERS=4
CMD ["python", "app.py"]

Environment Variable Configuration

Key environment variables for Docker deployments:

# Core configuration
ENV EPOCHLY_LEVEL=2
ENV EPOCHLY_MODE=conservative
ENV EPOCHLY_MAX_WORKERS=4
# Logging
ENV EPOCHLY_LOG_LEVEL=WARNING
ENV EPOCHLY_LOG_FILE=/var/log/epochly.log
# Monitoring
ENV EPOCHLY_PROMETHEUS_PORT=9090
# Emergency controls
ENV EPOCHLY_EMERGENCY_DISABLE=0

GPU Support (Level 4)

FROM nvidia/cuda:12.0-runtime-ubuntu22.04
RUN apt-get update && apt-get install -y python3.12 python3-pip
RUN pip install epochly cupy-cuda12x
WORKDIR /app
COPY . .
ENV EPOCHLY_LEVEL=4
ENV EPOCHLY_LICENSE_KEY=your-pro-license-key
ENV EPOCHLY_MODE=aggressive
CMD ["python3", "app.py"]

Running with GPU

# Run with GPU access
docker run --gpus all -e EPOCHLY_LEVEL=4 myapp
# Run with specific GPUs
docker run --gpus device=0,1 myapp
# Check GPU availability
docker run --gpus all myapp python -c "import epochly; print(epochly.get_status())"

Multi-Stage Build

# Build stage
FROM python:3.12-slim AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt epochly
# Runtime stage
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
ENV EPOCHLY_LEVEL=2
ENV EPOCHLY_AUTO_ENABLE=1
CMD ["python", "app.py"]

Resource Considerations

CPU and Memory Limits

# Run with resource limits
docker run --cpus="4" --memory="4g" myapp
# Match workers to available CPUs
docker run --cpus="2" -e EPOCHLY_MAX_WORKERS=2 myapp
LevelCPUsMemoryExample Command
122GBdocker run --cpus="2" --memory="2g"
22-42-4GBdocker run --cpus="4" --memory="4g"
34-84-8GBdocker run --cpus="8" --memory="8g"
48+8GB+docker run --gpus all --memory="16g"

Docker Compose

version: '3.8'
services:
app:
build: .
environment:
- EPOCHLY_LEVEL=2
- EPOCHLY_MODE=conservative
- EPOCHLY_MAX_WORKERS=4
- EPOCHLY_LOG_LEVEL=WARNING
deploy:
resources:
limits:
cpus: '4'
memory: 4G
reservations:
cpus: '2'
memory: 2G
volumes:
- ./logs:/var/log
ports:
- "9090:9090" # Prometheus metrics

Health Check

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 CMD python -c "import epochly; assert epochly.get_status()['initialized']" || exit 1

Custom Health Endpoint

# Install curl for HTTP health checks
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
HEALTHCHECK --interval=30s --timeout=5s CMD curl -f http://localhost:8080/health/epochly || exit 1

Logging Configuration

FROM python:3.12-slim
WORKDIR /app
# Create log directory
RUN mkdir -p /var/log/epochly
RUN pip install --no-cache-dir epochly
COPY . .
# Configure logging
ENV EPOCHLY_LOG_LEVEL=WARNING
ENV EPOCHLY_LOG_FILE=/var/log/epochly/app.log
ENV EPOCHLY_LOG_FORMAT=json
# Ensure logs are visible in docker logs
RUN ln -sf /dev/stdout /var/log/epochly/app.log
CMD ["python", "app.py"]

Viewing Logs

# View container logs
docker logs -f myapp
# View Epochly-specific logs
docker exec myapp tail -f /var/log/epochly.log
# Copy logs from container
docker cp myapp:/var/log/epochly.log ./epochly.log

Graceful Shutdown Handling

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir epochly
COPY . .
ENV EPOCHLY_LEVEL=2
ENV EPOCHLY_DOCKER_FAST_SHUTDOWN=1
# Use SIGTERM for graceful shutdown
STOPSIGNAL SIGTERM
CMD ["python", "app.py"]

Application Code

import signal
import epochly
def shutdown_handler(signum, frame):
print("Shutting down Epochly...")
epochly.shutdown()
exit(0)
signal.signal(signal.SIGTERM, shutdown_handler)
signal.signal(signal.SIGINT, shutdown_handler)
# Your application code

Debugging Tips

Enable Debug Logging

docker run -e EPOCHLY_LOG_LEVEL=DEBUG myapp

Interactive Debugging

# Run container interactively
docker run -it myapp /bin/bash
# Inside container
epochly doctor
python -c "import epochly; print(epochly.get_status())"

Check Epochly Status

# From outside container
docker exec myapp python -c "import epochly; print(epochly.get_status())"
# View metrics
docker exec myapp curl localhost:9090/metrics | grep epochly

CI/CD Integration

GitHub Actions

name: Build and Test with Epochly
on: [push]
jobs:
docker:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build Docker image
run: docker build -t myapp .
- name: Test with Epochly
run: |
docker run -e EPOCHLY_LEVEL=2 myapp python -m pytest
- name: Verify Epochly health
run: |
docker run myapp python -c "import epochly; assert epochly.get_status()['initialized']"

GitLab CI

docker-build:
stage: build
image: docker:latest
services:
- docker:dind
script:
- docker build -t myapp .
- docker run -e EPOCHLY_LEVEL=2 myapp python -m pytest
- docker run myapp epochly doctor

Production Dockerfile Example

# Multi-stage build for production
FROM python:3.12-slim AS builder
WORKDIR /build
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt epochly
# Runtime stage
FROM python:3.12-slim
# Create non-root user
RUN useradd -m -u 1000 appuser
WORKDIR /app
# Copy dependencies from builder
COPY --from=builder /root/.local /home/appuser/.local
COPY --chown=appuser:appuser . .
# Install sitecustomize
RUN pip install --no-cache-dir epochly && epochly sitecustomize install && epochly sitecustomize validate
# Configure Epochly
ENV PATH=/home/appuser/.local/bin:$PATH
ENV EPOCHLY_LEVEL=2
ENV EPOCHLY_MODE=conservative
ENV EPOCHLY_MAX_WORKERS=4
ENV EPOCHLY_LOG_LEVEL=WARNING
ENV EPOCHLY_LOG_FILE=/var/log/epochly.log
ENV EPOCHLY_DOCKER_FAST_SHUTDOWN=1
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s CMD python -c "import epochly; assert epochly.get_status()['initialized']" || exit 1
USER appuser
STOPSIGNAL SIGTERM
CMD ["python", "app.py"]