amq-adapter-python/DEPLOYMENT.md

FastAPI Demo - Docker Swarm Deployment

This guide explains how to deploy the FastAPI demo application to an existing Docker Swarm cluster.

Prerequisites

• Docker Swarm cluster already running
• Docker CLI installed and configured
• Access to the swarm manager node

Files Created

1. Dockerfile.demo - Docker image for the FastAPI application
2. docker-stack.yml - Docker Swarm stack configuration
3. prometheus.yml - Prometheus configuration for metrics collection
4. deploy-stack.sh - Automated deployment script

Quick Deployment

Option 1: Using the deployment script (Recommended)

./deploy-stack.sh

This script will:

• Check if Docker is running
• Initialize Docker Swarm if needed
• Build the Docker image
• Deploy the stack
• Show service status and access URLs

Option 2: Manual deployment

1. Build the Docker image:

   docker build -f Dockerfile.demo -t fastapi-demo:latest .
   

2. Deploy the stack:

   docker stack deploy -c docker-stack.yml fastapi-demo
   

Services Deployed

The stack deploys the following services:

1. FastAPI Demo Application (fastapi-demo)

• Ports: 8000 (app), 8001 (metrics)
• Image: fastapi-demo:latest
• Features:
  • FastAPI application with OpenTelemetry integration
  • Prometheus metrics endpoint
  • File upload functionality
  • Health checks
  • Resource limits and reservations

2. Jaeger Tracing (Optional)

• Ports: 16686 (UI), 4317 (OTLP gRPC)
• Image: jaegertracing/all-in-one:latest
• Purpose: Distributed tracing visualization

3. Prometheus Monitoring (Optional)

• Ports: 9090 (UI)
• Image: prom/prometheus:latest
• Purpose: Metrics collection and visualization

Access URLs

After successful deployment:

• FastAPI Application: http://localhost:8000
• FastAPI Documentation: http://localhost:8000/docs
• Prometheus Metrics: http://localhost:8001/metrics
• Jaeger UI: http://localhost:16686
• Prometheus UI: http://localhost:9090

Configuration

Environment Variables

The FastAPI demo service uses these environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT: Jaeger OTLP endpoint (default: http://jaeger:4317)
• OTEL_DEBUG_CONSOLE_TRACES: Enable console trace output (default: false)
• OTEL_EXPORTER_PROMETHEUS_HOST: Prometheus metrics host (default: 0.0.0.0)
• OTEL_EXPORTER_PROMETHEUS_PORT: Prometheus metrics port (default: 8001)

Properties File

The otdemo/otdemo.properties file is automatically included in the Docker image and available at the relative path ./otdemo/otdemo.properties within the container.

Management Commands

View Stack Status

docker stack services fastapi-demo

View Service Logs

docker service logs fastapi-demo_fastapi-demo

Scale Services

docker service scale fastapi-demo_fastapi-demo=2

Update Stack

docker stack deploy -c docker-stack.yml fastapi-demo

Remove Stack

docker stack rm fastapi-demo

Monitoring

Health Checks

The FastAPI service includes health checks that verify the application is responding:

• Endpoint: /docs
• Interval: 30 seconds
• Timeout: 10 seconds
• Retries: 3

Resource Limits

• CPU: 0.5 cores (limit), 0.25 cores (reservation)
• Memory: 512MB (limit), 256MB (reservation)

Metrics

The application exposes Prometheus metrics at /metrics including:

• documents_uploaded_total
• documents_metadata_processed_total
• documents_retrieved_total
• internal_api_call_duration_seconds

Troubleshooting

Service Not Starting

1. Check service logs: docker service logs fastapi-demo_fastapi-demo
2. Verify image was built: docker images | grep fastapi-demo
3. Check resource availability on nodes

Port Conflicts

If ports 8000, 8001, 16686, or 9090 are already in use, modify the docker-stack.yml file to use different ports.

Network Issues

The stack creates an overlay network demo-network. If you need to connect to external services, ensure they're on the same network or configure network routing appropriately.

Customization

Adding New Services

To add new services to the stack:

1. Add the service definition to docker-stack.yml
2. Include it in the demo-network
3. Configure appropriate resource limits and health checks

Modifying Configuration

• Application config: Modify demo.py and rebuild the image
• Prometheus config: Modify prometheus.yml
• Stack config: Modify docker-stack.yml

Environment-Specific Deployments

Create environment-specific stack files:

• docker-stack.dev.yml
• docker-stack.prod.yml
• docker-stack.staging.yml

Security Considerations

• The demo runs with minimal security for development purposes
• For production, consider:
  • Using secrets for sensitive configuration
  • Implementing proper authentication
  • Using HTTPS/TLS
  • Restricting network access
  • Running with non-root user