Migrate Dockerfile to Docker Hardened Images (DHI)

[nanotaboada]

Problem

The current Dockerfile uses the standard python:3.13.3-slim-bookworm base image, which contains 152 known vulnerabilities and a larger attack surface than necessary for production deployments. As security requirements become more stringent and compliance becomes increasingly important, we need a more secure, minimal, and actively maintained base image solution.

Pain points with the current approach:

• High number of CVEs in base images requiring constant monitoring and patching
• Lack of built-in SBOM (Software Bill of Materials) and provenance attestations
• No formal security compliance certifications (SLSA, CIS benchmarks)
• Larger attack surface due to unnecessary packages in the base image
• Manual effort required to stay current with security updates

Proposed Solution

Migrate the application's Dockerfile to use Docker Hardened Images (DHI) - Docker's official, minimal, and secure container base images. DHI provides:

• Up to 95% reduction in attack surface compared to standard images
• Near-zero CVEs actively maintained by Docker's security team
• Built-in compliance artifacts: SBOM, provenance attestations, SLSA Build Level 3
• Free and open source under Apache 2.0 license
• Drop-in replacement for existing Python images with minimal code changes

Expected behavior after implementation:

• Application continues to function identically
• Dramatically reduced vulnerability count in base images
• Automatic security updates and patching by Docker
• Enhanced security posture for production deployments
• Full supply chain transparency with built-in attestations

Suggested Approach

Technical Implementation Plan

1. Update Base Images

Builder Stage:

# Replace:
FROM python:3.13.3-slim-bookworm AS builder

# With:
FROM dhi.io/python:3.13-debian13-dev AS builder

Runtime Stage:

# Replace:
FROM python:3.13.3-slim-bookworm AS runtime

# With:
FROM dhi.io/python:3.13-debian13 AS runtime

2. Remove Redundant Build Dependencies

The DHI -dev variant already includes build tools, so remove this section from the builder stage:

# REMOVE THIS (already included in -dev image):
RUN apt-get update && \
    apt-get install -y --no-install-recommends build-essential gcc libffi-dev libssl-dev && \
    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*.deb

3. Update Health Check Implementation

Since DHI runtime images are minimal (distroless-style) and don't include curl by default, we need to adapt the health check.

Option A (Recommended): Python-based health check

Add a health endpoint to main.py:

@app.get("/health")
async def health():
    return {"status": "healthy", "version": "1.0.0"}

Update Dockerfile health check:

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9000/health')"]

Option B: Install curl if absolutely necessary

# In runtime stage, before USER fastapi
RUN apt-get update && apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

4. Update scripts/healthcheck.sh (if using Option A)

Modify to use Python instead of curl:

#!/bin/sh
python -c "import urllib.request; import sys; urllib.request.urlopen('http://localhost:9000/health'); sys.exit(0)" || exit 1

5. Key Files to Modify

• Dockerfile - Primary changes for base images and build process
• main.py - Add /health endpoint (if using Option A)
• scripts/healthcheck.sh - Update health check logic
• README.md - Document DHI usage and benefits
• .github/workflows/*.yml - Update CI/CD if authentication to dhi.io is needed

6. Architecture Considerations

• Multi-stage build preserved: Builder stage uses -dev variant, runtime uses minimal variant
• Non-root user maintained: DHI images run as non-root by default; our explicit fastapi user is kept for consistency
• Storage volume approach unchanged: /storage mount point works identically
• No application code changes required: Only infrastructure changes

7. Docker Registry Strategy

Phase 1: Direct Pull (Immediate)

# Authenticate to DHI registry
docker login dhi.io
# Use Docker Hub credentials

Phase 2: Mirror to Organization (Optional, for customization)

# Mirror DHI to your Docker Hub namespace
docker pull dhi.io/python:3.13-debian13
docker tag dhi.io/python:3.13-debian13 <your-org>/dhi-python:3.13-debian13
docker push <your-org>/dhi-python:3.13-debian13

Acceptance Criteria

Functional Requirements

• Application builds successfully using DHI base images
• All existing functionality works identically (API endpoints, database access, file operations)
• Container starts and stops correctly
• Health check passes consistently
• Application serves requests on port 9000
• Volume mounts work correctly (/storage directory)
• Non-root user (fastapi) operates without permission issues

Security & Compliance

• Docker Scout scan shows significantly reduced CVE count compared to previous image
• SBOM is available and complete (docker buildx imagetools inspect --format "{{json .SBOM}}")
• Provenance attestations are present
• Image signatures are verifiable
• No critical or high severity vulnerabilities in base image

Testing & Validation

• Unit tests pass in new container
• Integration tests pass
• Load testing shows no performance regression
• Health check endpoint responds correctly
• Container logs are captured correctly
• Application metrics/monitoring continue to work

Documentation

• README.md updated with DHI information
• Dockerfile includes comments explaining DHI usage
• Migration guide added to documentation
• CI/CD pipeline documentation updated if authentication changes required

Rollback Plan

• Previous Dockerfile backed up as Dockerfile.legacy
• Rollback procedure documented
• Ability to quickly revert to standard Python images if needed

References

Docker Hardened Images Documentation

• DHI Official Documentation
• DHI Quickstart Guide
• DHI Migration Guide
• DHI Python Images on Docker Hub

Security & Compliance

• DHI Security Features
• SBOM and Attestations
• Image Verification Guide
• SLSA Framework

Related Issues

• Security audit findings (if applicable)
• Compliance requirements tracking (if applicable)
• Previous vulnerability remediation efforts

Benchmarking Resources

• Compare DHI vs Standard Images
• Docker Scout Comparison Tool

Community Examples

• DHI Python Migration Examples
• FastAPI + DHI Best Practices

[coderabbitai]

🔗 Related PRs

#342 - feat: add multi-stage Dockerfile for building and running app [merged]
#350 - feat(docker): optimize multi-stage build using pre-built wheelhouse [merged]
#357 - chore(containers): comply with SonarQube docker:S6504 [merged]
#372 - chore: configure Black as the default Python code formatter [merged]
#434 - feat: migrate from runtime.txt to .python-version [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Migrate the FastAPI application's Dockerfile from python:3.13.3-slim-bookworm base images to Docker Hardened Images (DHI) to reduce vulnerabilities, minimize attack surface, and gain built-in security compliance artifacts while maintaining identical application functionality.

Observations

This is a FastAPI REST application using a two-stage Docker build (builder for wheel compilation, runtime for production). The application runs on port 9000 as a non-root fastapi user, with SQLite persistence at /storage. A /health endpoint already exists in routes/health_route.py, and the current health check mechanism relies on curl via scripts/healthcheck.sh. CI/CD uses GitHub Actions with GHCR for image publishing. The builder stage currently installs build tools via apt-get, and the runtime stage installs curl for health checks—both will need adjustment for DHI compatibility.

Assumptions

Assumption 1: Health Check Implementation Approach

Options Considered:

1. Python-based health check: Use Python's urllib to call the health endpoint, eliminating curl dependency
2. Install curl in runtime: Add apt-get install curl to maintain current healthcheck.sh approach

Chosen Option: 1

Rationale: Python-based health check aligns with DHI's minimal image philosophy and avoids adding unnecessary packages to the hardened runtime image.

Assumption 2: DHI Registry Authentication Strategy

Options Considered:

1. Add new secrets: Create DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets for dhi.io authentication
2. Use existing Docker Hub credentials: Leverage any pre-existing Docker Hub secrets in the repository

Chosen Option: 1

Rationale: Add explicit DHI-related secrets to clearly separate concerns and ensure proper authentication to dhi.io registry during builds.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Dockerfile Migration

This phase focuses on the fundamental infrastructure changes: backing up the current configuration for rollback capability, migrating to DHI base images, and adapting the health check mechanism to work without curl in the minimal DHI runtime environment.

Task 1: Create Rollback Backup

Create a backup of the existing Dockerfile to enable quick rollback if issues arise during or after the DHI migration.

• Copy current Dockerfile to Dockerfile.legacy in the repository root
• Add a header comment to Dockerfile.legacy explaining it's the pre-DHI backup for rollback purposes
• This satisfies the acceptance criteria requirement for a documented rollback plan

Task 2: Migrate to DHI Base Images and Remove Redundant Dependencies

Update the Dockerfile to use DHI base images and remove build dependencies that are now included in the DHI -dev variant.

• Update the builder stage FROM instruction in Dockerfile to use dhi.io/python:3.13-debian13-dev instead of python:3.13.3-slim-bookworm
• Update the runtime stage FROM instruction in Dockerfile to use dhi.io/python:3.13-debian13 instead of python:3.13.3-slim-bookworm
• Remove the apt-get command block in the builder stage that installs build-essential, gcc, libffi-dev, and libssl-dev (these are included in DHI -dev variant)
• Add comments above each FROM statement explaining the DHI image choice and its security benefits
• Preserve all other Dockerfile content: wheel building, COPY operations, non-root user setup, WORKDIR, EXPOSE, ENTRYPOINT, and CMD

Task 3: Adapt Health Check for DHI Runtime

Modify the health check implementation to use Python instead of curl, since DHI runtime images are minimal and don't include curl by default.

• Remove the apt-get command in the runtime stage that installs curl (the block containing apt-get install -y --no-install-recommends curl)
• Update the HEALTHCHECK instruction in Dockerfile to use a Python-based command: invoke Python with urllib.request to call http://localhost:9000/health
• Modify scripts/healthcheck.sh to use Python with urllib.request instead of curl, maintaining the same timeout behavior and exit code semantics
• Keep the existing health check timing parameters: 30s interval, 5s timeout, 5s start-period, 3 retries
• Note: The /health endpoint already exists in routes/health_route.py and requires no changes

🤖 Prompt for AI agents

This phase migrates the Dockerfile from standard Python images to Docker
Hardened Images (DHI) and adapts the health check mechanism to work without
curl.

Create rollback backup:
- Copy Dockerfile to Dockerfile.legacy
- Add header comment explaining it's a pre-DHI backup for rollback

Update Dockerfile base images:
- Change builder stage FROM to dhi.io/python:3.13-debian13-dev
- Change runtime stage FROM to dhi.io/python:3.13-debian13
- Remove apt-get install block for build-essential, gcc, libffi-dev, libssl-dev
from builder stage
- Add comments above FROM statements explaining DHI security benefits
- Preserve all other Dockerfile elements

Migrate health check to Python:
- Remove curl installation from runtime stage
- Update HEALTHCHECK instruction to use Python with urllib.request to call
http://localhost:9000/health
- Modify scripts/healthcheck.sh to use Python urllib.request instead of curl
- Maintain existing timing: 30s interval, 5s timeout, 5s start-period, 3 retries

Phase 2: CI/CD and Documentation Updates

This phase addresses the operational and documentation aspects: configuring GitHub Actions to authenticate with the DHI registry and updating documentation to reflect the new DHI-based approach.

Task 1: Configure DHI Registry Authentication in GitHub Actions

Update the CI/CD workflow to authenticate with dhi.io registry for pulling DHI base images during builds.

• Add a new Docker login step in .github/workflows/python-app.yml before the build step to authenticate with dhi.io
• The login should use secrets for Docker Hub credentials (dhi.io uses Docker Hub authentication)
• Document in the workflow file (via comments) that DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets must be configured in repository settings
• Keep the existing GHCR login and push configuration unchanged—only add DHI registry authentication for pulling base images
• Ensure the container job condition and triggers remain unchanged (push to master only)

Task 2: Update Documentation

Update project documentation to explain the DHI migration, its benefits, and provide guidance for developers.

• Add a new section to README.md explaining the DHI base images, their security benefits (reduced CVEs, SBOM, provenance attestations), and how to authenticate with dhi.io
• Include instructions for local development: how to run docker login dhi.io with Docker Hub credentials
• Document the rollback procedure: how to use Dockerfile.legacy to revert to standard Python images if needed
• Add inline comments throughout Dockerfile explaining DHI-specific choices and why certain patterns (like Python-based health check) are used

🤖 Prompt for AI agents

This phase configures CI/CD authentication for DHI registry and updates
documentation to reflect the migration.

Configure GitHub Actions:
- Add Docker login step to .github/workflows/python-app.yml before build step
- Authenticate with dhi.io using DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets
- Add comments documenting required secrets configuration
- Keep existing GHCR login and push unchanged
- Preserve job conditions and triggers

Update documentation:
- Add README.md section explaining DHI images and security benefits (reduced
CVEs, SBOM, provenance)
- Include local development instructions for docker login dhi.io
- Document rollback procedure using Dockerfile.legacy
- Add inline Dockerfile comments explaining DHI choices and patterns

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase migrates the Dockerfile from standard Python images to Docker
Hardened Images (DHI) and adapts the health check mechanism to work without
curl.

Create rollback backup:
- Copy Dockerfile to Dockerfile.legacy
- Add header comment explaining it's a pre-DHI backup for rollback

Update Dockerfile base images:
- Change builder stage FROM to dhi.io/python:3.13-debian13-dev
- Change runtime stage FROM to dhi.io/python:3.13-debian13
- Remove apt-get install block for build-essential, gcc, libffi-dev, libssl-dev
from builder stage
- Add comments above FROM statements explaining DHI security benefits
- Preserve all other Dockerfile elements

Migrate health check to Python:
- Remove curl installation from runtime stage
- Update HEALTHCHECK instruction to use Python with urllib.request to call
http://localhost:9000/health
- Modify scripts/healthcheck.sh to use Python urllib.request instead of curl
- Maintain existing timing: 30s interval, 5s timeout, 5s start-period, 3 retries
===============================================================================

Task: 2

This phase configures CI/CD authentication for DHI registry and updates
documentation to reflect the migration.

Configure GitHub Actions:
- Add Docker login step to .github/workflows/python-app.yml before build step
- Authenticate with dhi.io using DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets
- Add comments documenting required secrets configuration
- Keep existing GHCR login and push unchanged
- Preserve job conditions and triggers

Update documentation:
- Add README.md section explaining DHI images and security benefits (reduced
CVEs, SBOM, provenance)
- Include local development instructions for docker login dhi.io
- Document rollback procedure using Dockerfile.legacy
- Add inline Dockerfile comments explaining DHI choices and patterns

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[nanotaboada]

Cross-repo image size analysis — context for this issue

A cross-repo review of Docker image sizes across all six comparison projects adds the following context.

Python sits in the "larger" tier alongside TypeScript, .NET, and Java. Two size-reduction paths exist beyond DHI:

1. Alpine Python (python:3.13-alpine) — saves ~60–80 MB but introduces musl libc compatibility risk with native extensions (uvicorn's httptools, aiosqlite). The existing wheelhouse build pattern would need validation against Alpine before any switch.
2. DHI (Wolfi/Debian-based) — achieves similar savings without the musl risk. This is the recommended path and aligns with what this issue already proposes.

The existing wheelhouse approach in the builder stage is already well-suited to the DHI migration: the -dev builder variant handles compilation, and the runtime variant receives only pre-built wheels. Alpine Python is explicitly ruled out as unnecessarily risky for this stack given the native extension dependencies.

No changes to the proposed approach are needed.

[nanotaboada]

After further review, we've decided not to implement this change.

The security and compliance benefits of Docker Hardened Images (SBOM, provenance attestations, SLSA Build Level 3) are well-suited for production systems with formal compliance requirements. However, this project is educational in nature — the primary artifact is the source code, not the container image. The tradeoff doesn't justify the added friction:

• Rebuilding the image locally requires a one-time docker login dhi.io, since dhi.io requires authentication even for public images — unlike standard Docker Hub pulls
• Two additional CI/CD secrets (DHI_USERNAME / DHI_PASSWORD) to maintain across all six repos
• Introduces a dependency on a third-party registry (dhi.io) with its own availability surface

The existing Alpine-based images remain lean and sufficient for the project's goals. Closing as wontfix.