Published on

Local (PHP) Development with HTTPS, Traefik, mkcert and Docker

Authors

Local development environments often involve working on multiple projects simultaneously, and managing them efficiently can be a challenging task. Traefik is a popular reverse proxy that simplifies this process, allowing you to manage multiple projects seamlessly while also providing the capability to enable HTTPS/SSL for secure connections. In this guide, we will walk you through the steps to set up Traefik for local development, complete with HTTPS/SSL, using mkcert.

What is Traefik?

Traefik is a modern reverse proxy and load balancer designed for microservices and containerized applications. It is often used in development and production environments to route incoming requests to the appropriate services, making it a critical component in modern web application architectures. Traefik is particularly well-suited for handling dynamic and containerized environments, thanks to its ability to adapt to changes automatically.

What is mkcert?

mkcert is a simple and straightforward tool that allows you to generate valid SSL/TLS certificates for your local development environment. Its primary purpose is to make it easy to enable HTTPS on your local machine, ensuring that your local web applications can securely communicate using SSL/TLS, just like they would in a production environment.

mkcert simplifies the process of creating SSL certificates by providing a user-friendly command-line interface. It generates certificates that are trusted by your browser, preventing SSL warnings and ensuring a seamless and secure browsing experience for your local web applications.

Prerequisites

Before you begin, make sure you have the following prerequisites:

  • Docker: You should have Docker installed on your local machine.
  • mkcert: Install mkcert by following the instructions for your operating system. mkcert is used to generate SSL certificates for your local development environment.

Step 1: Create Infrastructure Directory

To get started, create a directory to organize everything related to your infrastructure:

mkdir infra

Step 2: Install Certificates with mkcert

Use mkcert to generate SSL certificates for your local domains. In your infra directory, create a certs folder to store the certificates:

cd infra/
mkdir certs
mkcert -cert-file certs/local-cert.pem -key-file certs/local-key.pem "docker.localhost" "*.docker.localhost" "l.susi.dev" "*.l.susi.dev"

For Windows/WSL setups, you'll need to copy the certificates to a location accessible for Windows:

cp -R /usr/local/share/ca-certificates/ /mnt/c/somewhere/accessible/for/windows

On Windows, open the copied folder and double-click the certificate to install/import it. For Firefox users, you may need to manually install the certificate via the browser settings.

Step 3: Configure Traefik

In your infra directory, create a config folder for Traefik configuration and create a traefik.yml file inside it with the following content:

global:
  sendAnonymousUsage: false

api:
  dashboard: true
  insecure: true

providers:
  docker:
    endpoint: 'unix:///var/run/docker.sock'
    watch: true
    exposedByDefault: false

  file:
    filename: /etc/traefik/dynamic.yml
    watch: true

log:
  level: INFO
  format: common

entryPoints:
  http:
    address: ':80'
    http:
      redirections:
        entryPoint:
          to: https
          scheme: https
  https:
    address: ':443'

This configuration enables the Traefik dashboard, sets up Docker as a provider, and specifies entry points for HTTP and HTTPS.

Step 4: Create a Dynamic Configuration

In the same config folder, create a dynamic.yml file with the following content:

http:
  routers:
    traefik:
      rule: 'Host(`traefik.docker.localhost`)'
      service: 'api@internal'
      tls:
        domains:
          - main: 'docker.localhost'
            sans:
              - '*.docker.localhost'
          - main: 'l.susi.dev'
            sans:
              - '*.l.susi.dev'

tls:
  certificates:
    - certFile: '/etc/certs/local-cert.pem'
      keyFile: '/etc/certs/local-key.pem'

This configuration sets up routers for the Traefik dashboard and specifies the SSL certificates to be used.

Step 5: Create Docker Compose Configuration

Go back to the infra directory and create a docker-compose.yml file:

version: '3'

services:
  reverse-proxy:
    image: traefik:v3.0
    container_name: traefik
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - 80:80
      - 443:443
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # Map the static configuration into the container
      - ./config/traefik.yml:/etc/traefik/traefik.yml:ro
      # Map the dynamic configuration into the container
      - ./config/dynamic.yml:/etc/traefik/dynamic.yml:ro
      # Map the certificates into the container
      - ./certs:/etc/certs:ro
    networks:
      - traefik

networks:
  traefik:
    external: true

This Docker Compose configuration sets up the Traefik container and maps the necessary volumes.

Step 6: Configure Your Projects

To make your projects known to Traefik, you need to add labels to the services in your project's Docker Compose file. For example:

services:
  app:
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.middlewares.t3demo-https-redirect.redirectscheme.scheme=https'
      - 'traefik.http.middlewares.t3demo.headers.accesscontrolallowmethods=GET,OPTIONS,PUT,POST'
      - 'traefik.http.middlewares.t3demo.headers.accesscontrolallowheaders=*'
      - 'traefik.http.middlewares.t3demo.headers.accesscontrolmaxage=100'
      - 'traefik.http.middlewares.t3demo.headers.customresponseheaders.X-Custom-Response-Header=foobar'
      - 'traefik.http.routers.t3demo.entrypoints=http'
      - 'traefik.http.routers.t3demo.rule=Host(`t3demo.l.susi.dev`)'
      - 'traefik.http.routers.t3demo.middlewares=t3demo-https-redirect'
      - 'traefik.http.routers.t3demo-https.entrypoints=https'
      - 'traefik.http.routers.t3demo-https.rule=Host(`t3demo.l.susi.dev`)'
      - 'traefik.http.routers.t3demo-https.tls=true'
      - 'traefik.http.routers.t3demo-https.service=t3demo'
      - 'traefik.http.routers.t3demo-https.middlewares=t3demo'
      - 'traefik.http.services.t3demo.loadbalancer.server.port=80'
      - 'traefik.docker.network=traefik'
    networks:
      - traefik
      - default

networks:
  traefik:
    external: true

Ensure that the traefik.docker.network label references the traefik network created in your Traefik configuration.

Traefik Dashboard

You can access your Traefik dashboard at:

Conclusion

By following these steps, you can set up Traefik for local development with HTTPS/SSL using mkcert. This configuration enables you to manage multiple projects seamlessly, providing secure connections for all your local development needs.

Hint: This configuration is based on the GitHub project: https://github.com/Heziode/traefik-v2-https-ssl-localhost