A self-hosted ACME server with a built-in CA and optional web interface.

• ✅ ACME Server implementation (supports http-01 challenge)
• 🔐 Built-in CA to sign/revoke certificates (can be replaced with an external CA), CA rollover is supported
• ✉️ Mail notifications (for account creation, expiring and expired certificates) with customizable templates
• 🌐 Web UI (certificate and domain log) with customizable templates

Tested with Certbot, Traefik, Caddy, uacme, acme.sh.

You can generate a new root CA key and certificate using OpenSSL:

openssl genrsa -out ca.key 4096
openssl req -new -x509 -nodes -days 3650 -subj "/C=DE/O=Demo" -key ca.key -out ca.pem

These two files (ca.key and ca.pem) will be imported into the container on first startup.

The container runs as a non-root user, so it must be able to read the key and certificate files. Make sure the permissions are set correctly:

chmod 600 ca.key ca.pem  # protect key from other users
chown 1000:1000 ca.key ca.pem  # ensures correct ownership

Once imported successfully, the CA data is stored in the database and you can remove the key files.

Docker Compose snippet:

services:

  acme-ca-server:
    image: knrdl/acme-ca-server
    restart: always
    environment:
      EXTERNAL_URL: https://acme.mydomain.org
      DB_DSN: postgresql://postgres:secret@db/postgres
    networks:
      - db_net
      - reverse_proxy_net
    volumes:
      - ./ca.key:/import/ca.key:ro # needed once to import new ca
      - ./ca.pem:/import/ca.pem:ro # needed once to import new ca
    mem_limit: 250m

  db:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_PASSWORD: secret  # use a strong password: `openssl rand -hex 32`
    networks:
      - db_net
    volumes:
      - ./db:/var/lib/postgresql/data
    mem_limit: 250m

networks:
  db_net:
  reverse_proxy_net:  # see next step

Serve the app securely using a TLS-terminating reverse proxy (like Apache, Nginx, Traefik or Caddy), e.g. at https://acme.mydomain.org

The app listens on port 8080 for HTTP traffic.

For a quick test you can skip the reverse proxy and expose the service directly:

services:
  acme-ca-server:
    # ...
    environment:
      EXTERNAL_URL: http://localhost:8080
    # ...
    ports:
      - "8080:8080"
    # ...

Don't do this in production. TLS usage is advised.

docker run -it --rm certbot/certbot certonly --server https://acme.mydomain.org/acme/directory --standalone --no-eff-email --email [email protected] -v --domains test1.mydomain.org

Templates consist of subject.txt and body.html (see here). Overwrite the following files:

• /app/mail/templates/cert-expired-info/{subject.txt,body.html}
• /app/mail/templates/cert-expires-warning/{subject.txt,body.html}
• /app/mail/templates/new-account-info/{subject.txt,body.html}

Template parameters:

• app_title: str application title from WEB_APP_TITLE
• app_desc: str application description from WEB_APP_DESCRIPTION
• web_url: str web index url from EXTERNAL_URL
• acme_url: str acme directory url
• domains: list[str] list of expiring domains
• expires_at: datetime domain expiration date
• expires_in_days: int days until cert will expire
• serial_number: str expiring certs serial number (hex)

Custom files to be served by the http server can be placed in /app/web/www.

Overwrite templates (see here):

• /app/web/templates/cert-log.html (Certificate Listing)
• /app/web/templates/domain-log.html (Domain Listing)
• /app/web/templates/index.html (Startpage)

Template parameters:

• app_title: str application title from WEB_APP_TITLE
• app_desc: str application description from WEB_APP_DESCRIPTION
• web_url: str web index url from EXTERNAL_URL
• acme_url: str acme directory url
• certs: list list of certs for cert-log.html
• domains: list list of domains for domain-log.html

First set env var CA_ENABLED=False. Then overwrite the file /app/ca/service.py (see here) in the docker image. It must provide two functions:

async def sign_csr(csr: x509.CertificateSigningRequest, subject_domain: str, san_domains: list[str]) -> SignedCertInfo:
    ...

• csr: a x509.CertificateSigningRequest object
• subject_domain: the main domain name for the certificate
• san_domains: subject alternative names, all domain names (including subject_domain) for the certificate
• returns: instance of SignedCertInfo()

class SignedCertInfo:
    cert: x509.Certificate
    cert_chain_pem: str

• cert: a x509.Certificate object
• cert_chain_pem: a PEM-encoded text file containing the created cert as well as the root or also intermediate cert. This file will be used by the ACME client

async def revoke_cert(serial_number: str, revocations: set[tuple[str, datetime]]) -> None:
    ...

• serial_number: certificate serial number to revoke as hex value
• revocations: all revoked certificates including the one specified by serial_number. It's a set of tuples containing (serial_number, revocation_date)
• returns: no error on success, throw exception otherwise

A custom CA backend must also handle the CRL (certificate revocation list) distribution.

flowchart LR
    accounts -->|1:0..n| orders
    orders -->|1:1..n| authorizations
    authorizations -->|1:1| challenges
    orders -->|1:0..1| certificates

cd tests/e2e
./run.sh
cd ../pytest
./run.sh
cd coverage
python3 -m http.server  # coverage report at localhost:8000