Docker Containerization

Overview

Docker containerization for the Chuuk Dictionary application including multi-stage builds, ML model packaging, OCR dependencies, and production deployment patterns.

Docker Architecture

chuuk/ ├── Dockerfile # Main application container ├── Dockerfile.ollama # Ollama LLM container ├── ollama-entrypoint.sh # Ollama startup script ├── docker-compose.yml # Local development └── .dockerignore

Main Application Dockerfile

Multi-stage build for Chuuk Dictionary

Stage 1: Build React frontend

FROM node:22-slim AS frontend-build

WORKDIR /app/frontend

Install dependencies first (better caching)

COPY frontend/package*.json ./ RUN npm ci --no-audit

Build frontend

COPY frontend/ ./ RUN npm run build

Stage 2: Python application

FROM python:3.11-slim

Set environment variables

ENV PYTHONDONTWRITEBYTECODE=1
PYTHONUNBUFFERED=1
PYTHONPATH=/app
TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata

WORKDIR /app

Install system dependencies

RUN apt-get update && apt-get install -y --no-install-recommends
# Tesseract OCR for image processing tesseract-ocr
tesseract-ocr-eng
# PDF processing poppler-utils
# Image libraries libgl1-mesa-glx
libglib2.0-0
libsm6
libxext6
libxrender-dev
# Build tools for some Python packages gcc
g++
# Clean up && rm -rf /var/lib/apt/lists/*

Install Python dependencies

COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt

Copy application code

COPY app.py . COPY src/ ./src/ COPY config/ ./config/ COPY data/ ./data/ COPY scripts/ ./scripts/

Copy ML models (large files)

COPY models/ ./models/

Copy built frontend from Stage 1

COPY --from=frontend-build /app/frontend/dist ./frontend/dist

Create necessary directories

RUN mkdir -p uploads logs output

Create non-root user

RUN useradd -m -u 1000 appuser &&
chown -R appuser:appuser /app USER appuser

Expose port

EXPOSE 8000

Health check

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3
CMD curl -f http://localhost:8000/health || exit 1

Run with Gunicorn

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "--timeout", "300", "app:app"]

Docker Ignore File

.dockerignore

Git

.git .gitignore .github

Python

pycache *.py[cod] *$py.class .Python *.so .pytest_cache .mypy_cache *.egg-info dist/ build/ eggs/ .eggs/

Virtual environments

venv/ .venv/ ENV/

Node

frontend/node_modules/ frontend/.vite/ frontend/dist/

IDE

.vscode/ .idea/ *.swp *.swo

Local development

.env .env.local *.log logs/

Test files

tests/ test_results/ htmlcov/ .coverage

Documentation

docs/ *.md !README.md

Temporary files

.tmp .temp uploads/ output/

Docker Compose for Development

docker-compose.yml

version: '3.8'

services: app: build: context: . dockerfile: Dockerfile ports: - "8000:8000" environment: - FLASK_ENV=development - COSMOS_CONNECTION_STRING=${COSMOS_CONNECTION_STRING} - FLASK_SECRET_KEY=${FLASK_SECRET_KEY} volumes: # Mount code for hot reload (dev only) - ./app.py:/app/app.py:ro - ./src:/app/src:ro # Persist uploads - ./uploads:/app/uploads - ./logs:/app/logs depends_on: - ollama networks: - chuuk-network

ollama: build: context: . dockerfile: Dockerfile.ollama ports: - "11434:11434" volumes: - ollama-models:/root/.ollama environment: - OLLAMA_HOST=0.0.0.0 networks: - chuuk-network deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

Local MongoDB for development

mongodb: image: mongo:7 ports: - "27017:27017" volumes: - mongodb-data:/data/db environment: - MONGO_INITDB_DATABASE=chuuk_dictionary networks: - chuuk-network

networks: chuuk-network: driver: bridge

volumes: ollama-models: mongodb-data:

Ollama Container

Dockerfile.ollama

FROM ollama/ollama:latest

Copy custom model configurations

COPY ollama-modelfile/ /modelfiles/ COPY ollama-entrypoint.sh /entrypoint.sh

RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

ollama-entrypoint.sh

#!/bin/bash

Start Ollama server in background

ollama serve &

Wait for server to be ready

sleep 10

Load custom Chuukese model if exists

if [ -f "/modelfiles/chuukese-translator.modelfile" ]; then echo "Loading Chuukese translator model..." ollama create chuukese-translator -f /modelfiles/chuukese-translator.modelfile fi

Keep container running

wait

Building and Running

Build Commands

Build main application

docker build -t chuuk-dictionary:latest .

Build with specific tag

docker build -t chuuk-dictionary:v1.0.0 .

Build without cache (fresh build)

docker build --no-cache -t chuuk-dictionary:latest .

Build for specific platform

docker build --platform linux/amd64 -t chuuk-dictionary:latest .

Build only frontend stage

docker build --target frontend-build -t chuuk-frontend:latest .

Run Commands

Run container

docker run -d
--name chuuk-app
-p 8000:8000
-e COSMOS_CONNECTION_STRING="$COSMOS_CONNECTION_STRING"
-e FLASK_SECRET_KEY="$FLASK_SECRET_KEY"
chuuk-dictionary:latest

Run with volume mounts

docker run -d
--name chuuk-app
-p 8000:8000
-v $(pwd)/uploads:/app/uploads
-v $(pwd)/logs:/app/logs
chuuk-dictionary:latest

Run interactively for debugging

docker run -it --rm
-p 8000:8000
chuuk-dictionary:latest /bin/bash

Run with GPU support

docker run -d
--gpus all
--name chuuk-app
-p 8000:8000
chuuk-dictionary:latest

Docker Compose Commands

Start all services

docker-compose up -d

Start with build

docker-compose up -d --build

View logs

docker-compose logs -f app

Stop services

docker-compose down

Stop and remove volumes

docker-compose down -v

Rebuild specific service

docker-compose build app docker-compose up -d app

Multi-Platform Builds

Build for Azure Container Apps (AMD64)

Enable buildx for multi-platform

docker buildx create --name chuuk-builder --use

Build and push for AMD64

docker buildx build
--platform linux/amd64
--push
-t myregistry.azurecr.io/chuuk-dictionary:latest
.

Build for Multiple Architectures

docker buildx build
--platform linux/amd64,linux/arm64
--push
-t myregistry.azurecr.io/chuuk-dictionary:latest
.

Optimization Strategies

Layer Caching

BAD: Invalidates cache on any code change

COPY . . RUN pip install -r requirements.txt

GOOD: Dependencies cached unless requirements change

COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . .

Reduce Image Size

Use slim base images

FROM python:3.11-slim

Install and clean in single RUN

RUN apt-get update && apt-get install -y --no-install-recommends
package1
package2
&& rm -rf /var/lib/apt/lists/*

Use --no-cache-dir for pip

RUN pip install --no-cache-dir -r requirements.txt

Remove build dependencies after use

RUN apt-get purge -y gcc g++ && apt-get autoremove -y

Multi-Stage for ML Models

Stage 1: Download/prepare models

FROM python:3.11-slim AS model-prep

RUN pip install huggingface_hub RUN python -c "from huggingface_hub import snapshot_download;
snapshot_download('Helsinki-NLP/opus-mt-mul-en', cache_dir='/models')"

Stage 2: Final image

FROM python:3.11-slim

COPY --from=model-prep /models /app/models

Debugging Containers

Inspect Running Container

View container logs

docker logs chuuk-app docker logs -f chuuk-app # Follow logs

Execute command in running container

docker exec -it chuuk-app /bin/bash

Check container stats

docker stats chuuk-app

Inspect container configuration

docker inspect chuuk-app

Debug Build Issues

Build with verbose output

docker build --progress=plain -t chuuk-dictionary:latest .

Build up to specific stage

docker build --target frontend-build -t debug:latest .

Check image layers

docker history chuuk-dictionary:latest

Analyze image size

docker images chuuk-dictionary:latest

Health Checks

Check container health status

docker inspect --format='{{.State.Health.Status}}' chuuk-app

View health check logs

docker inspect --format='{{json .State.Health}}' chuuk-app | jq

Security Best Practices

Non-Root User

Create user before copying files

RUN useradd -m -u 1000 appuser

Change ownership

COPY --chown=appuser:appuser . /app

Switch to non-root user

USER appuser

Secrets Management

NEVER put secrets in Dockerfile

BAD

ENV API_KEY=my-secret-key

GOOD: Use environment variables at runtime

docker run -e API_KEY="$API_KEY" myimage

BETTER: Use Docker secrets or Azure Key Vault

Scan for Vulnerabilities

Scan image for vulnerabilities

docker scout cves chuuk-dictionary:latest

Use trivy for scanning

trivy image chuuk-dictionary:latest

Production Considerations

Resource Limits

docker-compose.yml

services: app: deploy: resources: limits: cpus: '2' memory: 4G reservations: cpus: '1' memory: 2G

Logging Configuration

Configure logging driver

In docker-compose.yml or docker run

logging: driver: "json-file" options: max-size: "10m" max-file: "3"

Graceful Shutdown

In app.py

import signal import sys

def signal_handler(sig, frame): print('Shutting down gracefully...') # Cleanup code here sys.exit(0)

signal.signal(signal.SIGTERM, signal_handler) signal.signal(signal.SIGINT, signal_handler)

Common Issues and Solutions

Issue: Large Image Size

Check what's taking space

docker history --no-trunc chuuk-dictionary:latest

Solutions:

1. Use multi-stage builds

2. Use slim base images

3. Clean up in same RUN layer

4. Use .dockerignore

Issue: Slow Builds

Solutions:

1. Order Dockerfile by change frequency

2. Use BuildKit for parallel builds

DOCKER_BUILDKIT=1 docker build .

3. Use --cache-from for CI/CD

docker build --cache-from=myregistry/app:latest .

Issue: Container Won't Start

Check logs

docker logs chuuk-app

Run interactively

docker run -it chuuk-dictionary:latest /bin/bash

Check if port is in use

lsof -i :8000

Dependencies

Container includes:

Python 3.11
Node.js 22 (build stage)
Tesseract OCR with English language pack
Poppler PDF utilities
OpenCV dependencies
Gunicorn WSGI server

docker-containerization

Safety Notice

Copy this and send it to your AI assistant to learn

Multi-stage build for Chuuk Dictionary

Stage 1: Build React frontend

Install dependencies first (better caching)

Build frontend

Stage 2: Python application

Set environment variables

Install system dependencies

Install Python dependencies

Copy application code

Copy ML models (large files)

Copy built frontend from Stage 1

Create necessary directories

Create non-root user

Expose port

Health check

Run with Gunicorn

.dockerignore

Git

Python

Virtual environments

Node

IDE

Local development

Test files

Documentation

Temporary files

docker-compose.yml

Local MongoDB for development

Dockerfile.ollama

Copy custom model configurations

Start Ollama server in background

Wait for server to be ready

Load custom Chuukese model if exists

Keep container running

Build main application

Build with specific tag

Build without cache (fresh build)

Build for specific platform

Build only frontend stage

Run container

Run with volume mounts

Run interactively for debugging

Run with GPU support

Start all services

Start with build

View logs

Stop services

Stop and remove volumes

Rebuild specific service

Enable buildx for multi-platform

Build and push for AMD64

BAD: Invalidates cache on any code change

GOOD: Dependencies cached unless requirements change

Use slim base images

Install and clean in single RUN

Use --no-cache-dir for pip

Remove build dependencies after use

Stage 1: Download/prepare models

Stage 2: Final image

View container logs

Execute command in running container

Check container stats

Inspect container configuration

Build with verbose output

Build up to specific stage

Check image layers

Analyze image size

Check container health status

View health check logs

Create user before copying files

Change ownership

Switch to non-root user

NEVER put secrets in Dockerfile

BAD

GOOD: Use environment variables at runtime

BETTER: Use Docker secrets or Azure Key Vault

Scan image for vulnerabilities