Docker Deployment - Electronic Invoice Processing API

Overview

This guide covers deploying the Electronic Invoice Processing API using Docker containers. Docker provides a consistent, isolated environment for running the application across different platforms.

Prerequisites

Before starting, ensure you have:

Docker

Docker Engine 20.10+ installedDownload Docker

Docker Compose

Docker Compose v2.0+ installedInstall Compose

Project Files

Dockerfile

The project includes a Dockerfile that defines the container image:

dockerfile

# Usa una imagen base oficial de Python
FROM python:3.9-slim

# Establece el directorio de trabajo dentro del contenedor
WORKDIR /app

# Copia los archivos de requerimientos y los instala
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copia el resto del código de la aplicación
COPY . .

# Expone el puerto en el que la aplicación va a escuchar
EXPOSE 8000

# Define el comando para iniciar la aplicación con Uvicorn
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile Breakdown

Base Image: python:3.9-slim

Lightweight Python 3.9 image
Minimal size for faster builds and deployments

Working Directory: /app

All application files stored here

Dependencies:

Copies requirements.txt first (layer caching)
Installs Python packages with --no-cache-dir flag

Application Code:

Copies all source files to container

Exposed Port: 8000

FastAPI/Uvicorn default port

Startup Command:

Runs Uvicorn ASGI server
Binds to all network interfaces (0.0.0.0)

Docker Compose Configuration

The docker-compose.yml file simplifies container orchestration:

docker-compose.yml

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    command: uvicorn main:app --host 0.0.0.0 --port 8000

Configuration Breakdown

Version: 3.8

Docker Compose file format version

Service Name: web

Single service for the API

Build Context: . (current directory)

Builds from local Dockerfile

Port Mapping: 8000:8000

Host port 8000 → Container port 8000

Volume Mount: .:/app

Live code synchronization (development mode)
Changes reflect immediately without rebuild

Command Override:

Uses same Uvicorn command as Dockerfile

Deployment Methods

Docker Compose (Recommended)
Docker CLI

Using Docker Compose

Docker Compose is the recommended method for local development and simple deployments.

Navigate to Project Directory

cd /path/to/your/project

Build and Start Services

Build the Docker image and start the container:

docker-compose up --build

Use -d flag to run in detached mode (background):

docker-compose up -d --build

Verify Service is Running

Check that the service is up:

docker-compose ps

Expected output:

NAME                COMMAND                  SERVICE   STATUS    PORTS
project-web-1       "uvicorn main:app..."   web       Up        0.0.0.0:8000->8000/tcp

Test the API

Access the API documentation:

curl http://localhost:8000/docs

Or open in browser: http://localhost:8000/docs

Managing the Service

docker-compose stop

Using Docker Commands

For more control or CI/CD pipelines, use Docker CLI directly.

Build the Docker Image

docker build -t invoice-api:latest .

Tag format: name:version

invoice-api - Image name
latest - Version tag

Run the Container

docker run -d \
  --name invoice-api-container \
  -p 8000:8000 \
  -v $(pwd):/app \
  invoice-api:latest

Flags Explained:

-d - Run in detached mode (background)
--name - Container name for easy reference
-p - Port mapping (host:container)
-v - Volume mount for live code updates

Verify Container Status

docker ps

Look for invoice-api-container in the list.

Test the API

curl http://localhost:8000/docs

Managing Containers

docker stop invoice-api-container

Port Configuration

Default Port Mapping

The application uses port 8000 by default:

Host Port 8000 → Container Port 8000

Changing the Host Port

If port 8000 is already in use, modify the port mapping:

services:
  web:
    ports:
      - "8080:8000"  # Host:Container

Only change the host port (left side). The container port (8000) should remain unchanged as it’s configured in the application.

Accessing on Custom Port

After changing to port 8080:

API Docs: http://localhost:8080/docs
Endpoint: http://localhost:8080/process_excel

Volume Configuration

Development Volume

The default volume mount enables live code updates:

volumes:
  - .:/app

Development Mode Benefits:

Code changes reflect immediately
No need to rebuild container
Faster iteration cycle

Production Volume

For production, remove the volume mount or use specific volumes:

services:
  web:
    build: .
    ports:
      - "8000:8000"
    # volumes removed for production

Environment Variables

Adding Environment Variables

You can configure the application using environment variables:

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ENVIRONMENT=production
      - LOG_LEVEL=info
      - MAX_UPLOAD_SIZE=10485760

Example .env File

.env

ENVIRONMENT=production
LOG_LEVEL=info
MAX_UPLOAD_SIZE=10485760
CORS_ORIGINS=https://yourdomain.com

Add .env to .dockerignore to prevent copying sensitive data into the image.

Health Checks and Monitoring

Adding Health Checks

Enhance your docker-compose.yml with health checks:

docker-compose.yml

services:
  web:
    build: .
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/docs"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Viewing Health Status

docker-compose ps

Healthy service shows (healthy) status.

Viewing Logs

docker-compose logs -f web

Container Resource Usage

docker stats invoice-api-container

Shows CPU, memory, network I/O, and disk I/O in real-time.

Production Considerations

Remove Development Volume

Remove or restrict volume mounts to prevent code modification in production.

Configure CORS Properly

Restrict CORS origins to specific domains. See CORS Configuration.

Use Environment Variables

Store sensitive configuration in environment variables, not in code.

Enable Health Checks

Implement health check endpoints for container orchestration.

Set Resource Limits

Define CPU and memory limits to prevent resource exhaustion.

Use Specific Tags

Avoid latest tag in production. Use specific version tags.

Resource Limits Example

docker-compose.yml

services:
  web:
    build: .
    ports:
      - "8000:8000"
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Troubleshooting

Port Already in Use

Error: Bind for 0.0.0.0:8000 failed: port is already allocatedSolution:

Find process using the port:
```
lsof -i :8000
```
Kill the process or change port mapping:
```
ports:
  - "8080:8000"
```

Build Fails on Dependencies

Error: ERROR: Could not find a version that satisfies the requirement...Solution:

Ensure requirements.txt is present and valid
Verify Python version compatibility
Try building with no cache:
```
docker-compose build --no-cache
```

Container Exits Immediately

Error: Container status shows Exited (1)Solution:

Check logs for errors:
```
docker-compose logs web
```
Verify main.py exists and is valid
Test locally without Docker first

Cannot Access API

Error: Connection refused or timeoutSolution:

Verify container is running:
```
docker-compose ps
```
Check port mapping is correct
Ensure firewall allows port 8000

Try accessing from container:

docker-compose exec web curl http://localhost:8000/docs

Code Changes Not Reflected

Error: Updated code doesn’t run in containerSolution:

Verify volume mount is configured:
```
volumes:
  - .:/app
```
Restart the container:
```
docker-compose restart
```
If still not working, rebuild:
```
docker-compose up --build
```

Next Steps

CORS Configuration

Configure CORS for production security

API Reference

Learn how to use the API endpoints

Excel Format

Understand required Excel file format

Docker Documentation

Official Docker documentation

Getting Started

Core Concepts

Guides

​Overview

​Prerequisites

Docker

Docker Compose

​Project Files

​Dockerfile

​Docker Compose Configuration

​Deployment Methods

​Using Docker Compose

​Managing the Service

​Using Docker Commands

​Managing Containers

​Port Configuration

​Default Port Mapping

​Changing the Host Port

​Accessing on Custom Port

​Volume Configuration

​Development Volume

​Production Volume

​Environment Variables

​Adding Environment Variables

​Example .env File

​Health Checks and Monitoring

​Adding Health Checks

​Viewing Health Status

​Viewing Logs

​Container Resource Usage

​Production Considerations

Remove Development Volume

Configure CORS Properly

Use Environment Variables

Enable Health Checks

Set Resource Limits

Use Specific Tags

​Resource Limits Example

​Troubleshooting

​Next Steps

CORS Configuration

API Reference

Excel Format

Docker Documentation

Build docs developers (and LLMs) love

Overview

Prerequisites

Project Files

Dockerfile

Docker Compose Configuration

Deployment Methods

Using Docker Compose

Managing the Service

Using Docker Commands

Managing Containers

Port Configuration

Default Port Mapping

Changing the Host Port

Accessing on Custom Port

Volume Configuration

Development Volume

Production Volume

Environment Variables

Adding Environment Variables

Example .env File

Health Checks and Monitoring

Adding Health Checks

Viewing Health Status

Viewing Logs

Container Resource Usage

Production Considerations

Resource Limits Example

Troubleshooting

Next Steps