Install

The Certificate Manager is one container with one data volume. The web portal, the API, issuing and scheduled renewals all run inside it. Plan on about ten minutes.

Before you start

Tip: you do not need the DNS details yet. The setup guide asks for them later and tests them for you.

Step 1: Download the file

On the server, make an empty folder and download one file into it. The Downloads page shows this command with the right address filled in:

mkdir cert-manager && cd cert-manager
curl -fsSLO https://<this website>/downloads/docker-compose.yml

That is all the configuration needed. The portal listens on port 8080.

Step 2: Optional settings

Nothing is required. To change the port or add other options, create a file named .env next to docker-compose.yml, for example:

PORTAL_PORT=9443

Data key: the portal creates its encryption key on first start and shows it once, right after you create the administrator. Save it in your password manager. For stronger protection, put it in .env as DATA_KEY=... afterwards so it no longer sits on the server's data volume.

Step 3: Start it

docker compose up -d

The first start takes a few seconds. Then show your one-time setup code:

docker compose logs cert-manager | grep "FIRST RUN"

You will see a line like this (your code is different):

FIRST RUN: no administrator password is set. Open https://<this portal>/auth/setup
and enter setup code 7F3K-92QX-M4TB to choose the password for "admin".

No output? Wait a few more seconds and run it again, or look at the whole log with docker compose logs cert-manager. The code stays valid until you use it, and a new one is printed every time the container restarts before setup is done.

Step 4: Open the portal

The portal's first address is simply this server plus the port you chose:

So with those examples you open http://10.0.0.5:8080/auth/setup. Make sure your firewall allows that port from your desk.

1. Enter the setup code exactly as shown, including the dashes.
2. Choose the password for the administrator admin: at least 12 characters.
3. You are signed in, and the setup guide opens.

Continue with the first run. You can give the portal a proper name such as https://certs.example.com now or later: see below.

Give it a proper name and HTTPS

For day-to-day use you will want an address like https://certs.example.com instead of an IP and port. Three steps:

1. Create a DNS record. In your DNS, add an A record such as certs.example.com pointing at the server's IP address.
2. Add HTTPS. Pick one of the two options below.
3. Tell the portal its address. In Config → Settings → General → Public address (also asked in the setup guide), enter https://certs.example.com. It is used in e-mail links and for single sign-on.

Option A: behind your reverse proxy (recommended)

If you already run nginx, Traefik, HAProxy, Caddy or a load balancer, point it at http://<server>:<PORTAL_PORT> and let it handle the certificate. A minimal nginx example:

server {
    listen 443 ssl;
    server_name certs.example.com;
    ssl_certificate     /etc/ssl/certs.example.com.pem;
    ssl_certificate_key /etc/ssl/certs.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_buffering off;   # live progress when issuing
    }
}

Option B: the portal serves HTTPS itself

Put a certificate and key for certs.example.com in a tls folder next to docker-compose.yml, then in .env set:

TLS_CERT_FILE=/run/tls/portal.crt
TLS_KEY_FILE=/run/tls/portal.key
TLS_LISTEN_ADDR=:8443

and uncomment the two HTTPS lines in docker-compose.yml (the 443:8443 port and the ./tls folder). Run docker compose up -d again and open https://certs.example.com.

Tip: once the portal is running, it can issue the certificate for its own name. Issue certs.example.com, download it as full chain and key, put it in tls/ (or on your proxy), and it renews like any other.

Upgrading

Download docker-compose.yml again from the Downloads page (it names the new version), then:

docker compose pull && docker compose up -d

Your data stays in the volume.

Never run docker compose down -v. The -v deletes the volume, and with it every certificate.