caddis-plugin: Instructions file for GitHub Copilot

Docker & Containerization Instructions

Best practices for creating optimized, secure, and efficient Docker images for applications.

Core Principles

1. Immutability

• Build new images for every change
• Never modify running containers
• Use semantic versioning for image tags
• Avoid latest tag in production

2. Efficiency

• Minimize image size
• Optimize layer caching
• Use multi-stage builds
• Remove unnecessary dependencies

3. Security

• Run as non-root user
• Scan for vulnerabilities
• Use minimal base images
• Don't store secrets in images

4. Portability

• Design images to run consistently across environments (local, cloud, on-premise)
• Externalize all environment-specific config via environment variables
• Use multi-platform base images when targeting multiple architectures (ARM, x86)
• Include all dependencies explicitly; don't rely on host system packages

5. Isolation

• Run a single primary process per container
• Use container networking for inter-container communication (not host networking)
• Use named volumes for persistent data rather than bind mounts when possible

Dockerfile Template

Python Application (FastAPI)

# ============================================
# Stage 1: Build
# ============================================
FROM python:3.11-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# ============================================
# Stage 2: Production
# ============================================
FROM python:3.11-slim AS production

WORKDIR /app

# Create non-root user
RUN useradd --create-home --shell /bin/bash --uid 1000 appuser

# Copy dependencies from builder
COPY --from=builder /root/.local /home/appuser/.local

# Update PATH for user-installed packages
ENV PATH="/home/appuser/.local/bin:$PATH"

# Copy application code
COPY --chown=appuser:appuser src/ ./src/
COPY --chown=appuser:appuser main.py .

# Switch to non-root user
USER appuser

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Expose port
EXPOSE 8000

# Run application
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]