Enable Apache SSL in Docker for local development

Enable Apache SSL in Docker for local development

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Enable Apache SSL in Docker for local development

Getting a self-signed certificate to work inside a Docker container often feels like chasing your tail, especially when you are just trying to spin up a local stack without touching production infrastructure. The error ERR_SSL_PROTOCOL_ERROR in Chrome is the classic symptom of a mismatch between what the browser expects and what the server is actually presenting. It usually means the handshake failed before any data was exchanged, or the certificate presented wasn't trusted by the client for the specific hostname used.

In scenarios where you are dockerizing an older application using images like php:5.6.30-apache, the default configuration often lacks the necessary certificates and permissions required to serve HTTPS traffic securely. Simply adding a2enmod ssl to your Dockerfile and exposing port 443 is only half the battle; you must also provide the certificate files and ensure Apache knows to use them for specific virtual hosts.

The core issue in many local setups is that the container expects SSL certificates at /etc/ssl/certs/localhost.crt and /etc/ssl/private/localhost.key, but these files do not exist by default in the php:5.6.30-apache image, nor are they automatically generated upon startup unless you configure a specific directory for self-signed generation.

To resolve this within Docker, you have two primary paths: generating certificates dynamically at runtime or baking them into your image build. The dynamic approach is generally preferred for local development because it eliminates the need to rebuild the image every time you want to switch from HTTP to HTTPS. You can achieve this by creating a custom entrypoint script that generates a self-signed certificate using OpenSSL only if they do not already exist.

Here is how you can structure the build and runtime logic:

First, ensure your Dockerfile sets up the environment to accept certificates. While enabling the module (a2enmod ssl) is correct, Apache needs a place to look for the keys. You can configure Apache to auto-generate a self-signed certificate on first run by creating an .ssl directory and setting up a specific virtual host configuration that points to it.

FROM php:5.6.30-apache

MAINTAINER Tzook Bar Noy

# Install SSL certificate generation tools
RUN apt-get update && apt-get install -y openssl ca-certificates

# Enable required modules
RUN a2enmod rewrite ssl

# Create directory for self-signed certs if they don't exist
RUN mkdir -p /etc/apache2/ssl

# Copy your custom vhost config
COPY default /etc/apache2/sites-available/000-default.conf

# Set up an entrypoint script to handle certificate generation
COPY generate-ssl.sh /usr/local/bin/generate-ssl.sh
RUN chmod +x /usr/local/bin/generate-ssl.sh

CMD ["/usr/local/bin/generate-ssl.sh", "apache2"]

The generate-ssl.sh script acts as a gatekeeper. It checks if the certificate files exist in /etc/apache2/ssl. If they are missing, it runs openssl req -x509 -newkey rsa:2048 -keyout /etc/apache2/ssl/cert.key -out /etc/apache2/ssl/cert.crt to create them. Crucially, this script must also update the Apache configuration to point the SSL virtual host to these newly generated files.

In your docker-compose.yml, you must expose both ports 80 and 443. However, simply exposing port 443 is not enough if your browser connects via http://admin.local.app.io. Browsers enforce strict security policies; if the URL scheme in the address bar does not match the protocol expected by the server configuration, or if the hostname doesn't match the certificate Common Name (CN), you will see the protocol error.

Ensure your virtual host configuration explicitly defines the SSL parameters:

<VirtualHost *:443>
    ServerAdmin admin@admin.io
    DocumentRoot /var/www/html/app/htdocsAdmin
    ServerName admin.local.app.io
    
    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/cert.crt
    SSLCertificateKeyFile /etc/apache2/ssl/cert.key
    
    # Optional: Add HSTS for local dev if you want to force HTTPS
    # Header always set Strict-Transport-Security "max-age=31536000"
</VirtualHost>

<VirtualHost *:80>
    ServerAdmin admin@admin.io
    DocumentRoot /var/www/html/app/htdocsAdmin
    ServerName admin.local.app.io
    
    # Redirect HTTP to HTTPS for security consistency
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
</VirtualHost>

A common pitfall is ignoring the hostname mismatch. If your certificate is generated with CN=localhost but you access the site via admin.local.app.io, Chrome will reject it immediately because it cannot verify the identity of the server. The script generating the certificate must include -subj "/CN=admin.local.app.io" to match the DNS name you are using in the browser.

Another subtle issue arises with volume mounting. If your application code resides in a volume mapped to /var/www/html, ensure that directory permissions allow Apache to read it. In some older PHP versions, SELinux or AppArmor might interfere, but in standard Docker setups, permission issues usually manifest as "403 Forbidden" rather than SSL errors.

For local development workflows where you want to avoid complex certificate management entirely, consider using tools like mkcert. While the source material focuses on native OpenSSL generation, understanding the underlying mechanics of how Apache validates certificates is essential for debugging future issues. If you move towards more modern PHP versions or frameworks like Laravel, the ecosystem provides better out-of-the-box support for Let's Encrypt integration via acme.sh or similar tools, which can automate the issuance and renewal of valid domain-validated certificates even in Docker environments.

Ultimately, the ERR_SSL_PROTOCOL_ERROR is a signal that the trust chain is broken. By ensuring the certificate matches the hostname, providing the correct key files to Apache, and configuring the virtual host to listen on port 443 with SSLEngine on, you can seamlessly enable HTTPS for your local development environment without requiring external infrastructure or complex network configurations.

Our network