docker.recipes

Step-CA Certificate Authority

advanced

Step-CA private certificate authority for internal TLS certificates.

Overview

Step-CA is an open-source certificate authority server developed by Smallstep Labs that provides a modern, API-driven approach to managing X.509 certificates and SSH certificates. Unlike traditional heavyweight PKI solutions, Step-CA offers a lightweight, cloud-native certificate authority that supports ACME protocol, OAuth/OIDC integration, and programmatic certificate management through REST APIs. The platform was designed to address the complexity and operational overhead of traditional certificate authorities while providing enterprise-grade security features. This Docker deployment creates a private certificate authority using Step-CA with ACME protocol support enabled, allowing automated certificate issuance and renewal for internal infrastructure. The configuration includes remote management capabilities through the Step CLI and web interface, making it suitable for organizations that need to manage TLS certificates across multiple services without relying on public certificate authorities. The ACME integration enables compatibility with tools like cert-manager, Traefik, and other automated certificate management systems. This stack is ideal for DevOps teams, security engineers, and organizations requiring internal PKI infrastructure with modern management capabilities. Companies with microservices architectures, Kubernetes clusters, or internal web services will benefit from Step-CA's automated certificate provisioning and short-lived certificate approach, which reduces the risk associated with long-lived certificates and manual certificate management processes.

Key Features

  • ACME protocol support for automated certificate issuance and renewal compatible with Let's Encrypt clients
  • REST API and CLI-based certificate management with support for X.509 and SSH certificates
  • OAuth/OIDC integration for identity-based certificate authentication and authorization
  • Configurable certificate templates and policies for controlling certificate attributes and validity periods
  • Built-in support for short-lived certificates with automatic renewal workflows
  • Remote management capabilities through Step CLI and web-based administrative interface
  • Hardware Security Module (HSM) and cloud KMS integration for root key protection
  • Certificate revocation lists (CRL) and Online Certificate Status Protocol (OCSP) support

Common Use Cases

  • 1Internal PKI infrastructure for Kubernetes clusters requiring automatic TLS certificate management
  • 2Microservices environments needing mutual TLS authentication between service components
  • 3Development and staging environments requiring trusted certificates without public CA dependencies
  • 4Organizations implementing zero-trust network architectures with certificate-based authentication
  • 5Homelab and self-hosted service deployments requiring proper TLS certificates for internal domains
  • 6CI/CD pipelines requiring temporary certificates for testing and deployment automation
  • 7Enterprise environments replacing manual certificate processes with automated PKI workflows

Prerequisites

  • Minimum 512MB RAM and 1GB disk space for certificate storage and CA operations
  • Port 9000 available for Step-CA HTTPS API and web interface access
  • Step CLI installed on management workstations for CA administration and certificate operations
  • Basic understanding of PKI concepts including certificate chains, root CAs, and ACME protocol
  • DNS resolution configured for CA hostname to ensure proper certificate validation
  • Backup strategy planned for CA private keys and certificate database in step_ca_data volume

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  step-ca: 
3    image: smallstep/step-ca:latest
4    container_name: step-ca
5    volumes: 
6      - step_ca_data:/home/step
7    ports: 
8      - "9000:9000"
9    environment: 
10      - DOCKER_STEPCA_INIT_NAME=${CA_NAME}
11      - DOCKER_STEPCA_INIT_DNS_NAMES=localhost,step-ca
12      - DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true
13      - DOCKER_STEPCA_INIT_ACME=true
14    restart: unless-stopped
15    networks: 
16      - step-ca-network
17
18volumes: 
19  step_ca_data: 
20
21networks: 
22  step-ca-network: 
23    driver: bridge

.env Template

.env
1# Step-CA
2CA_NAME=My Private CA

Usage Notes

  1. 1CA at https://localhost:9000
  2. 2Get root CA: docker exec step-ca step ca root
  3. 3ACME enabled for auto-renewal
  4. 4Use step CLI for management
  5. 5Install root CA on clients

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  step-ca:
5    image: smallstep/step-ca:latest
6    container_name: step-ca
7    volumes:
8      - step_ca_data:/home/step
9    ports:
10      - "9000:9000"
11    environment:
12      - DOCKER_STEPCA_INIT_NAME=${CA_NAME}
13      - DOCKER_STEPCA_INIT_DNS_NAMES=localhost,step-ca
14      - DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true
15      - DOCKER_STEPCA_INIT_ACME=true
16    restart: unless-stopped
17    networks:
18      - step-ca-network
19
20volumes:
21  step_ca_data:
22
23networks:
24  step-ca-network:
25    driver: bridge
26EOF
27
28# 2. Create the .env file
29cat > .env << 'EOF'
30# Step-CA
31CA_NAME=My Private CA
32EOF
33
34# 3. Start the services
35docker compose up -d
36
37# 4. View logs
38docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/step-ca-certificates/run | bash

Troubleshooting

  • Certificate validation fails with 'x509: certificate signed by unknown authority': Install the root CA certificate on client systems using 'step ca root' command output
  • ACME client fails with '404 directory not found': Verify ACME is enabled and access the directory at https://localhost:9000/acme/acme/directory
  • Step-CA container exits with 'no configuration found': Initialize the CA properly by ensuring DOCKER_STEPCA_INIT_NAME environment variable is set on first run
  • Remote management returns 'connection refused': Check that port 9000 is accessible and DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT is set to true
  • Certificate requests fail with 'provisioner not found': Verify the ACME provisioner is configured correctly and check available provisioners with 'step ca provisioner list'

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

step-ca

Tags

#step-ca#certificates#pki#tls#security

Category

Security & Networking

Related Recipes

Ad Space