Step-CA Provisioner Client for Traefik¶

A lightweight sidecar container for Traefik Proxy that automatically provisions and renews certificates from a Step CA server.

The primary use case for this sidecar is when using Traefik in a Docker Swarm environment. It is deployed as a single replica to any manager node and automatically discovers and configures TLS certificates for services that have the appropriate labels.

Note

This project is not affiliated with Smallstep nor Traefik. It is a community project created by JoKneeMo. If you're using Step CA and Traefik in a production or enterprise environment, please consider purchasing a subscription from them.

Features¶

Automatic Discovery: Scans Docker labels on Traefik services.
Dynamic Configuration: Generates Traefik dynamic configuration (YAML) for TLS certificates.
Renewal: Automatically renews certificates before they expire.
Flexible Config: Configurable via environment variables.

Usage¶

Run alongside Traefik in your docker-compose.yml.

See docker-compose.yml for a more complete example.

services:
  stepclient:
    image: ghcr.io/jokneemo/stepclient:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./certificates:/certificates # Map to the same path used in Traefik
      - ./traefik/conf/stepclient.yaml:/stepclient.yaml
    environment:
      STEP_CA_URL: https://stepca.example.com
      STEP_FINGERPRINT: ...
      STEP_PROVISIONER: jwk-provisioner
      # Secrets (mapped via docker secrets or file mounts)
      STEP_PROVISIONER_KEY: /run/secrets/stepca_key
      STEP_PASSWORD_FILE: /run/secrets/stepca_password

Configuration¶

Environment Variable	Default	Description
`INTERVAL_SECONDS`	`300`	Check interval in seconds (default 5 minutes)
`RENEW_BEFORE_HOURS`	`480`	Renewal threshold in hours (default 20 days)
`ISSUE_IF_TLS_TRUE`	`true`	Only issue if `traefik.http.routers.x.tls=true`
`IGNORE_IF_CERTRESOLVER_PRESENT`	`true`	Ignore routers with existing certresolver
`NOT_AFTER`	`1128h`	Certificate lifetime duration (default 47 days)
`STEP_CA_URL`		Step CA URL, e.g. `https://stepca.example.com:9000`
`STEP_FINGERPRINT`		Step CA SHA256 Fingerprint
`STEP_PROVISIONER`		Step CA JWK Provisioner Name
`STEP_PROVISIONER_KEY`	`/run/secrets/stepca_key`	Path to provisioner key
`STEP_PASSWORD_FILE`	`/run/secrets/stepca_password`	Path to password file
`OUTPUT_DIR`	`/certificates`	Directory to write certificates, mount at the same path used in Traefik
`TRAEFIK_YAML_PATH`	`/stepclient.yaml`	Path to Traefik dynamic configuration file

Development¶

Install dependencies:
```
pip install -e .
```
Run locally:
```
stepclient-traefik
```