Adding Trusted Root CA Certificates to Alpine Docker Containers

When building Docker containers based on Alpine Linux in corporate environments with SSL/TLS inspection firewalls, you may encounter certificate verification errors during package installation with apk. This occurs because the firewall acts as a man-in-the-middle (MITM), presenting certificates signed by a custom corporate Certificate Authority (CA) that's not trusted by Alpine's default CA store.

Problem: Certificate Verification Failure

In environments with MITM SSL inspection, you'll see errors like:

SSL routines:tls_process_server_certificate:certificate verify failed
WARNING: Ignoring https://dl-cdn.alpinelinux.org/alpine/v3.13/main: Permission denied

This prevents package installation because Alpine cannot verify the authenticity of the repository's SSL certificate.

Solution Approaches

Method 1: Manual Certificate Append (Quick Fix)

The simplest approach is to directly append your custom CA certificate to Alpine's certificate store:

FROM alpine:latest

# Copy your custom CA certificate
COPY corporate-ca.crt /tmp/corporate-ca.crt

# Append to the certificate bundle
RUN cat /tmp/corporate-ca.crt >> /etc/ssl/certs/ca-certificates.crt

# Install packages
RUN apk --no-cache add curl ca-certificates

WARNING

This approach works but may be overwritten if update-ca-certificates runs later. Use this only for simple cases.

Method 2: Proper Certificate Installation

For a more robust solution that persists through certificate updates:

FROM alpine:latest

# Copy certificate to the correct location
COPY corporate-ca.crt /usr/local/share/ca-certificates/corporate-ca.crt

# Add certificate to the trust store
RUN apk --no-cache add ca-certificates \
    && update-ca-certificates

# Install additional packages
RUN apk --no-cache add curl

Method 3: Using --no-check-certificate Flag

For Alpine 3.18+, use the --no-check-certificate flag to bypass certificate verification initially:

FROM alpine:latest

# Temporarily disable certificate verification to install ca-certificates
RUN apk --no-cache add --no-check-certificate ca-certificates

# Copy and add your custom CA certificate
COPY corporate-ca.crt /usr/local/share/ca-certificates/corporate-ca.crt
RUN update-ca-certificates

# Install other packages
RUN apk --no-cache add curl

TIP

This method is particularly useful when you need to install ca-certificates package but can't verify the repository's SSL certificate initially.

Complete Working Example

Here's a comprehensive Dockerfile that handles corporate CA certificates properly:

FROM alpine:latest

USER root

# Copy corporate CA certificate
COPY corporate-ca.crt /usr/local/share/ca-certificates/corporate-ca.crt

# Temporarily append certificate to allow apk to work
RUN cat /usr/local/share/ca-certificates/corporate-ca.crt >> /etc/ssl/certs/ca-certificates.crt

# Install ca-certificates and properly add our certificate
RUN apk --no-cache add ca-certificates \
    && rm -rf /var/cache/apk/* \
    && update-ca-certificates

# Install additional packages
RUN apk --no-cache add curl

Best Practices

• Certificate Format: Ensure your certificate is in PEM format (base64 encoded with -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers)
• Certificate Location: Use /usr/local/share/ca-certificates/ for custom certificates
• Clean Up: Remove certificate caches and temporary files to keep your image lean
• Security: Be cautious when adding corporate CAs, as this trusts all certificates signed by that authority

Troubleshooting

If you still encounter issues:

1. Verify your certificate format is correct
2. Check that the certificate file has proper permissions
3. Confirm the certificate is in the correct directory for update-ca-certificates
4. Test connectivity with curl -v https://dl-cdn.alpinelinux.org to diagnose SSL issues

By properly configuring your Alpine Docker containers to trust corporate CA certificates, you can maintain security while working within corporate network environments that perform SSL inspection.