Guide to install and configure Cert Warden

Cert Warden keeps SSL certificates in one place and serves them to servers: it obtains and renews them itself via ACME (Let’s Encrypt), while clients fetch the files with API keys and restart their services. This is convenient when there are many domains and servers: one server is responsible for all certificates, and no certbot is needed on each server.

Where we install

We will deploy it on the Remnawave panel server. Any other server works too.

Domain validation

The DNS-01 method: Cloudflare has its own provider, Gcore and Bunny.net connect through lego.

Serving clients

The Cert Warden client on each server downloads certificates and restarts the services.

Authors and projects

Two projects this guide is built on, and the person who helped build the page itself.

Cert Warden

The certificate server of this guide: obtains and renews certificates via ACME, proves domains with DNS-01 and serves them to clients by API keys.

gregtwallace@gregtwallace

↗ certwarden

Client fork

The client from the “Fork” tab: polls the server on a schedule, opens no ports and needs no AES key.

mishkatik@mishkatik

↗ certwarden-client

Guide help

This Cert Warden guide is co-authored: the structure, the steps and the wording of this page were worked out together with maposia.

Roleguide co-authorHelpedshape the structure, steps and text

maposia@maposia

How it works

Cert Warden orders certificates from Let’s Encrypt and proves domain ownership with a DNS-01 record at the DNS provider. It stores the issued certificates and serves them to clients via API keys: the client on each server polls Cert Warden every few hours, and when there is an update it downloads the pem files, writes them to disk and restarts its web server. A panel behind Caddy needs no file certificates at all: Caddy obtains them on its own.

Installation and configuration of Cert Warden

Important

We will install Cert Warden on the Remnawave panel server, but you can install it on any other server. Domain ownership is verified with the DNS-01 method: Cloudflare, Gcore and Bunny.net are covered below.

Important

We will use the dns-01 Cloudflare method, but you can use other methods.

1. Create a directory for Cert Warden and create docker-compose.yml

   mkdir /opt/certwarden && cd /opt/certwarden && nano docker-compose.yml

   Insert the following content:

   docker-compose.yml

   services:
     certwarden:
       container_name: certwarden
       image: ghcr.io/gregtwallace/certwarden:latest
       restart: unless-stopped
       ports:
         - '127.0.0.1:4050:4050'
       volumes:
         - ./certwarden-data:/app/data
       networks:
         - remnawave-network
       logging:
         driver: 'json-file'
         options:
           max-size: '30m'
           max-file: '5'
   
   networks:
     remnawave-network:
       name: remnawave-network
       driver: bridge
       external: true

2. Run Cert Warden

   cd /opt/certwarden && docker compose up -d && docker compose logs -f

3. Add Cert Warden to the panel web server so its interface is available on its own domain:

   Nginx

   cd /opt/remnawave && nano nginx.conf

   Add upstream section:

   nginx.conf

   upstream certwarden {
       server 127.0.0.1:4050;
   }

   Add server section:

   nginx.conf

   server {
       listen 443 ssl;
       server_name certwarden.yourdomain.com; # Don't forget to add a DNS record in Cloudflare
       http2 on;
   
       ssl_certificate "/etc/nginx/ssl/yourdomain.com/fullchain.pem";
       ssl_certificate_key "/etc/nginx/ssl/yourdomain.com/privkey.pem";
       ssl_trusted_certificate "/etc/nginx/ssl/yourdomain.com/fullchain.pem";
   
       location / {
           proxy_pass http://certwarden;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }

   Restart nginx:

   cd /opt/remnawave && docker compose down remnawave-nginx && docker compose up -d remnawave-nginx

   Caddy

   cd /opt/remnawave && nano Caddyfile

   Add the Cert Warden site at the end of the file:

   Caddyfile

   certwarden.yourdomain.com {
       reverse_proxy 127.0.0.1:4050
   }

   Caddy obtains the certificate for this domain on its own, just like for the panel.

   Restart Caddy:

   cd /opt/remnawave && docker compose restart remnawave-caddy

4. Open your browser and go to the link

   Important

   Don’t forget to add a DNS record for your domain in Cloudflare

   https://certwarden.yourdomain.com

5. Login to the system using the login admin and password password

   

6. We will be redirected to the main page

   

7. Go to the Settings section and change our current password

Provider Setup

1. Go to the Providers section

2. Click on New Provider

3. Select DNS-01 Cloudflare

4. In the Domains field, enter the domain for which we will be receiving wildcard certificates

5. In the API Access Method field, select API Token. Instructions for creating a token with Zone:Edit permissions can be found in the official Cloudflare documentation

   

6. Click on the Submit button

Private Key Setup

1. Go to the Private Keys section

2. Click on New Key

3. In the Name field, enter the name of the key (for example, ACME)

4. In the Key Generation Algorithm field, select ECDSA P-384 (recommended algorithm for high security and compatibility)

5. Check the Disable API Key box

6. Click on the Submit button

7. A new window will pop up with our Private Key, also click on the Submit button

   

ACME Accounts Setup

1. Go to the ACME Accounts section

2. Click on New Account

3. In the Name field, enter the name of our domain or your own other name

4. In the Contact E-mail Address field, enter the email to which notifications will be sent

5. In the ACME Server field, select Let’s Encrypt

6. In the Private Key field, select your previously created key

7. Check the Accept ACME Server`s Terms of Service box

8. Click on the Submit button

9. A window with account data will pop up

   

10. Click on the REGISTER button and the Account Status should become Valid

11. Click on the Submit button

Certificates Setup

1. Go to the Certificates section

2. Click on New Certificate

3. In the Name field, enter the name of our domain or your own other name

4. In the ACME Account field, select the previously created account

5. In the Subject (and Common Name) field, enter the domain 2 levels, for example example.com

6. Click on the ADD button and in the Alternate Name 1 field enter the already wildcard domain *.example.com

7. Click on the Submit button

   

8. A window with ACME Orders will pop up

   

9. Click on the PLACE NEW ORDER button

10. Now we wait for the certificate to be received, we can track the status in the ACME Queue section, as soon as the domain disappears, the certificate is received

11. Go to the Dashboard section and see that the certificate is received and how many days are left until the expiration date

    

Cert Warden Client

The Cert Warden client runs as a Docker container: it fetches certificates from the server using API keys, saves the files to disk and restarts the specified containers so the services pick up the update.

The guide covers both versions of the client. The official client is the primary option here: the server pushes the certificate to the client, so the client keeps a port open and decrypts the payload with an AES key. The alternative, the mishkatik/certwarden-client fork, flips the scheme: the client polls the server itself, opens no ports and needs no AES key.

How the fork behaves:

Polling on a schedule

At startup and then once per configured interval the client makes a single request to Cert Warden. If the certificate has not changed, the server answers with an empty 304 and nothing is downloaded.

IntervalCW_CLIENT_POLL_INTERVAL, 6 hours by default

First start

On the first start the client does not wait for the renewal window: it downloads the certificate right away, writes the files and restarts the containers.

Filesfullchain.pem and privkey.pem

Renewal window

A renewed certificate is written within the configured time window, 02:00 to 03:00 in the example below, and the containers are restarted afterwards.

WindowFILE_UPDATE_TIME_START / FILE_UPDATE_TIME_ENDDaysFILE_UPDATE_DAYS_OF_WEEKTime zonefrom the TZ variable, UTC without it

Retry on failure

If the server is unreachable or an API key is wrong, the client keeps running: it logs an error and retries.

First pause15 minutesBackoffthe pause doubles after each failureLimitthe poll interval

Note

The fork needs Cert Warden server 0.18.2 or newer. The ghcr.io/gregtwallace/certwarden:latest image from the guide above qualifies.

Panel behind Caddy

If the panel runs behind Caddy, it needs no separate certificate files: Caddy obtains and renews them on its own. The Cert Warden client is then needed for the other services with file certificates, such as the nginx on nodes.

Client on the Remnawave panel server

Official client

1. Create a directory for the client:

   mkdir -p /opt/certwardenclient/certs && cd /opt/certwardenclient && nano docker-compose.yml

   Insert the following content:

   docker-compose.yml

   services:
       certwardenclient:
         image: ghcr.io/gregtwallace/certwarden-client:latest
         container_name: certwardenclient
         restart: unless-stopped
         ports:
           - '127.0.0.1:5055:5055'
         volumes:
           - /var/run/docker.sock:/var/run/docker.sock
           - /opt/certwardenclient/certs:/opt/certwarden/certs
         environment:
           TZ: "Europe/Moscow"
           CW_CLIENT_FILE_UPDATE_TIME_START: "02:00"
           CW_CLIENT_FILE_UPDATE_TIME_END: "03:00"
           CW_CLIENT_FILE_UPDATE_DAYS_OF_WEEK: "Mon Tue Wed Thu Fri Sat Sun"
           CW_CLIENT_RESTART_DOCKER_CONTAINER0: "remnawave-nginx"
           CW_CLIENT_AES_KEY_BASE64: "pLZEc_QvSka8syfQtuTfArblalMKU6C6Ke1uIji0E5g"
           CW_CLIENT_SERVER_ADDRESS: "https://certwarden.example.com"
           CW_CLIENT_KEY_NAME: "example.com"
           CW_CLIENT_KEY_APIKEY: "0UkmZEZK7oieQ6hmz9Fta2obMMZRjAuo"
           CW_CLIENT_CERT_NAME: "example.com"
           CW_CLIENT_CERT_APIKEY: "MkYMf7eXO8aB9xiNKqwvNVcDGKJ0Dg6v"
           CW_CLIENT_CERT_PATH: "/opt/certwarden/certs"
           CW_CLIENT_KEY_PEM_FILENAME: "privkey.pem"
           CW_CLIENT_CERTCHAIN_PEM_FILENAME: "fullchain.pem"
         networks:
           - remnawave-network
         logging:
           driver: 'json-file'
           options:
             max-size: '30m'
             max-file: '5'
   
   networks:
       remnawave-network:
         name: remnawave-network
         driver: bridge
         external: true

   CW_CLIENT_RESTART_DOCKER_CONTAINER0 is set to remnawave-nginx. For a panel behind Caddy, use remnawave-caddy.

2. CW_CLIENT_AES_KEY_BASE64 is the key from the Certificates → Post Processing → Client AES Key section. Click GENERATE to obtain it.

   

3. CW_CLIENT_SERVER_ADDRESS is the address of the Cert Warden server, for example https://certwarden.example.com.

4. CW_CLIENT_KEY_NAME and CW_CLIENT_KEY_APIKEY are the name and the API key of the private key from the Private Keys section.

5. CW_CLIENT_CERT_NAME and CW_CLIENT_CERT_APIKEY are the name and the API key of the certificate from the Certificates section.

6. Run the client:

   cd /opt/certwardenclient && docker compose up -d && docker compose logs -f

7. The fullchain.pem and privkey.pem files should appear in the /opt/certwardenclient/certs folder.

8. Mount them in the panel’s docker-compose.yml:

   cd /opt/remnawave && nano docker-compose.yml

   Add to volumes, do not forget to specify your domain:

   docker-compose.yml

   volumes:
     - /opt/certwardenclient/certs/fullchain.pem:/etc/nginx/ssl/yourdomain.com/fullchain.pem
     - /opt/certwardenclient/certs/privkey.pem:/etc/nginx/ssl/yourdomain.com/privkey.pem

9. Restart nginx:

   cd /opt/remnawave && docker compose down remnawave-nginx && docker compose up -d remnawave-nginx

Fork

1. Check the certificate settings in Cert Warden: under Certificates → Post Processing → Client, the client address and the Client AES Key must be empty. The client fetches the certificate itself, there is nowhere to send it. If anything is filled in there, the server logs an error on every renewal.

2. Create a directory for the client:

   mkdir -p /opt/certwardenclient/certs && cd /opt/certwardenclient && nano docker-compose.yml

   Insert the following content:

   docker-compose.yml

   services:
       certwardenclient:
         image: ghcr.io/mishkatik/certwarden-client:latest
         container_name: certwardenclient
         restart: unless-stopped
         volumes:
           - /var/run/docker.sock:/var/run/docker.sock
           - /opt/certwardenclient/certs:/opt/certwarden/certs
         environment:
           TZ: "Europe/Moscow"
           CW_CLIENT_SERVER_ADDRESS: "https://certwarden.example.com"
           CW_CLIENT_POLL_INTERVAL: "6h"
           CW_CLIENT_0_CERT_NAME: "example.com"
           CW_CLIENT_0_CERT_APIKEY: "MkYMf7eXO8aB9xiNKqwvNVcDGKJ0Dg6v"
           CW_CLIENT_0_KEY_APIKEY: "0UkmZEZK7oieQ6hmz9Fta2obMMZRjAuo"
           CW_CLIENT_0_FILE_UPDATE_TIME_START: "02:00"
           CW_CLIENT_0_FILE_UPDATE_TIME_END: "03:00"
           CW_CLIENT_0_FILE_UPDATE_DAYS_OF_WEEK: "Mon Tue Wed Thu Fri Sat Sun"
           CW_CLIENT_0_RESTART_DOCKER_CONTAINER0: "remnawave-nginx"
           CW_CLIENT_0_CERT_PATH: "/opt/certwarden/certs"
           CW_CLIENT_0_KEY_PEM_FILENAME: "privkey.pem"
           CW_CLIENT_0_CERTCHAIN_PEM_FILENAME: "fullchain.pem"
         logging:
           driver: 'json-file'
           options:
             max-size: '30m'
             max-file: '5'

   CW_CLIENT_0_RESTART_DOCKER_CONTAINER0 is set to remnawave-nginx. For a panel behind Caddy, use remnawave-caddy.

   Pinning the image version

   The latest tag starts pointing to a new image over time. Check the current digest with docker buildx imagetools inspect ghcr.io/mishkatik/certwarden-client:latest (the same output shows the build attestations: the image is built by CI from the fork repository). To keep the version from changing without your participation, use the digest instead of the tag: ghcr.io/mishkatik/certwarden-client@sha256:<digest>. The digest is immutable: the image updates only when you replace it in the compose files yourself.

3. CW_CLIENT_SERVER_ADDRESS is the address of the Cert Warden server, for example https://certwarden.example.com. It must start with https://, otherwise the client does not start.

4. CW_CLIENT_POLL_INTERVAL sets how often to poll the server: 30m, 6h, 12h and so on, but no more often than once a minute. The server logs every request, so a very short interval floods its log.

5. CW_CLIENT_0_CERT_NAME and CW_CLIENT_0_CERT_APIKEY are the name and the API key of the certificate from the Certificates section.

6. CW_CLIENT_0_KEY_APIKEY is the API key of the private key the certificate uses (the Private Keys section). If you switch the certificate to another key on the server, update this variable and restart the client.

7. CW_CLIENT_0_FILE_UPDATE_TIME_START, CW_CLIENT_0_FILE_UPDATE_TIME_END and CW_CLIENT_0_FILE_UPDATE_DAYS_OF_WEEK set the window in which the client writes a renewed certificate and restarts the containers. The time follows the TZ time zone, or UTC without it.

8. Run the client:

   cd /opt/certwardenclient && docker compose up -d && docker compose logs -f

9. The fullchain.pem and privkey.pem files should appear in the /opt/certwardenclient/certs folder.

10. Mount them in the panel’s docker-compose.yml:

    cd /opt/remnawave && nano docker-compose.yml

    Add to volumes, do not forget to specify your domain:

    docker-compose.yml

    volumes:
      - /opt/certwardenclient/certs/fullchain.pem:/etc/nginx/ssl/yourdomain.com/fullchain.pem
      - /opt/certwardenclient/certs/privkey.pem:/etc/nginx/ssl/yourdomain.com/privkey.pem

11. Restart nginx:

    cd /opt/remnawave && docker compose down remnawave-nginx && docker compose up -d remnawave-nginx

Moving from the official client

If the client is already running the official variant (the ghcr.io/gregtwallace/certwarden-client image):

1. In Cert Warden, clear the client address and the Client AES Key under Certificates → Post Processing → Client of the certificate.
2. In /opt/certwardenclient/docker-compose.yml, change the image to ghcr.io/mishkatik/certwarden-client:latest, remove ports and the CW_CLIENT_AES_KEY_BASE64 and CW_CLIENT_KEY_NAME variables.
3. Recreate the container: cd /opt/certwardenclient && docker compose up -d.

The fork understands the variables without an index (CW_CLIENT_CERT_NAME and the rest), so rewriting them to CW_CLIENT_0_* is optional.

Several certificates and containers

Another certificate is added with a block of variables with index 1: CW_CLIENT_1_CERT_NAME, CW_CLIENT_1_CERT_APIKEY, CW_CLIENT_1_KEY_APIKEY and so on. Give it its own file names (CW_CLIENT_1_KEY_PEM_FILENAME, CW_CLIENT_1_CERTCHAIN_PEM_FILENAME) so the certificates do not overwrite each other. Extra containers to restart go into CW_CLIENT_0_RESTART_DOCKER_CONTAINER1, CW_CLIENT_0_RESTART_DOCKER_CONTAINER2 and so on, numbered without gaps.

Client on the Remnawave node server

Note

The client is installed the same way on other nodes that will receive certificates from Cert Warden. You can do without it: on a node server the script itself can issue and renew certificates (item 11 “Manage certificates domain” → “Update current certificates”), and when a node is added through the menu, its certificates are deployed automatically. The Cert Warden client is only needed if you want to distribute all certificates from one place.

Official client

1. Create a directory for the client:

   mkdir -p /opt/certwardenclient/certs && cd /opt/certwardenclient && nano docker-compose.yml

   Insert the following content:

   docker-compose.yml

   services:
       certwardenclient:
         image: ghcr.io/gregtwallace/certwarden-client:latest
         container_name: certwardenclient
         restart: unless-stopped
         ports:
           - '127.0.0.1:5055:5055'
         volumes:
           - /var/run/docker.sock:/var/run/docker.sock
           - /opt/certwardenclient/certs:/opt/certwarden/certs
         environment:
           TZ: "Europe/Moscow"
           CW_CLIENT_FILE_UPDATE_TIME_START: "02:00"
           CW_CLIENT_FILE_UPDATE_TIME_END: "03:00"
           CW_CLIENT_FILE_UPDATE_DAYS_OF_WEEK: "Mon Tue Wed Thu Fri Sat Sun"
           CW_CLIENT_RESTART_DOCKER_CONTAINER0: "remnawave-nginx"
           CW_CLIENT_AES_KEY_BASE64: "pLZEc_QvSka8syfQtuTfArblalMKU6C6Ke1uIji0E5g"
           CW_CLIENT_SERVER_ADDRESS: "https://certwarden.example.com"
           CW_CLIENT_KEY_NAME: "example.com"
           CW_CLIENT_KEY_APIKEY: "0UkmZEZK7oieQ6hmz9Fta2obMMZRjAuo"
           CW_CLIENT_CERT_NAME: "example.com"
           CW_CLIENT_CERT_APIKEY: "MkYMf7eXO8aB9xiNKqwvNVcDGKJ0Dg6v"
           CW_CLIENT_CERT_PATH: "/opt/certwarden/certs"
           CW_CLIENT_KEY_PEM_FILENAME: "privkey.pem"
           CW_CLIENT_CERTCHAIN_PEM_FILENAME: "fullchain.pem"
         logging:
           driver: 'json-file'
           options:
             max-size: '30m'
             max-file: '5'

2. CW_CLIENT_AES_KEY_BASE64 is the key from the Certificates → Post Processing → Client AES Key section. Click GENERATE to obtain it.

3. CW_CLIENT_SERVER_ADDRESS is the address of the Cert Warden server.

4. CW_CLIENT_KEY_NAME and CW_CLIENT_KEY_APIKEY are the name and the API key from the Private Keys section.

5. CW_CLIENT_CERT_NAME and CW_CLIENT_CERT_APIKEY are the name and the API key from the Certificates section.

6. Run the client:

   cd /opt/certwardenclient && docker compose up -d && docker compose logs -f

7. The fullchain.pem and privkey.pem files should appear in the /opt/certwardenclient/certs folder.

8. Mount them in the node’s docker-compose.yml (its web server is also called remnawave-nginx):

   cd /opt/remnanode && nano docker-compose.yml

   docker-compose.yml

   volumes:
     - /opt/certwardenclient/certs/fullchain.pem:/etc/nginx/ssl/yourdomain.com/fullchain.pem
     - /opt/certwardenclient/certs/privkey.pem:/etc/nginx/ssl/yourdomain.com/privkey.pem

9. Restart the node’s nginx:

   cd /opt/remnanode && docker compose down remnawave-nginx && docker compose up -d remnawave-nginx

Fork

1. Create a directory for the client:

   mkdir -p /opt/certwardenclient/certs && cd /opt/certwardenclient && nano docker-compose.yml

   Insert the following content:

   docker-compose.yml

   services:
       certwardenclient:
         image: ghcr.io/mishkatik/certwarden-client:latest
         container_name: certwardenclient
         restart: unless-stopped
         volumes:
           - /var/run/docker.sock:/var/run/docker.sock
           - /opt/certwardenclient/certs:/opt/certwarden/certs
         environment:
           TZ: "Europe/Moscow"
           CW_CLIENT_SERVER_ADDRESS: "https://certwarden.example.com"
           CW_CLIENT_POLL_INTERVAL: "6h"
           CW_CLIENT_0_CERT_NAME: "example.com"
           CW_CLIENT_0_CERT_APIKEY: "MkYMf7eXO8aB9xiNKqwvNVcDGKJ0Dg6v"
           CW_CLIENT_0_KEY_APIKEY: "0UkmZEZK7oieQ6hmz9Fta2obMMZRjAuo"
           CW_CLIENT_0_FILE_UPDATE_TIME_START: "02:00"
           CW_CLIENT_0_FILE_UPDATE_TIME_END: "03:00"
           CW_CLIENT_0_FILE_UPDATE_DAYS_OF_WEEK: "Mon Tue Wed Thu Fri Sat Sun"
           CW_CLIENT_0_RESTART_DOCKER_CONTAINER0: "remnawave-nginx"
           CW_CLIENT_0_CERT_PATH: "/opt/certwarden/certs"
           CW_CLIENT_0_KEY_PEM_FILENAME: "privkey.pem"
           CW_CLIENT_0_CERTCHAIN_PEM_FILENAME: "fullchain.pem"
         logging:
           driver: 'json-file'
           options:
             max-size: '30m'
             max-file: '5'

2. Fill in the variables the same way as on the panel server: CW_CLIENT_SERVER_ADDRESS is the address of the Cert Warden server, CW_CLIENT_0_CERT_NAME and CW_CLIENT_0_CERT_APIKEY come from the Certificates section, CW_CLIENT_0_KEY_APIKEY from the Private Keys section. If the node receives a different certificate, its Post Processing → Client must be empty too.

3. Run the client:

   cd /opt/certwardenclient && docker compose up -d && docker compose logs -f

4. The fullchain.pem and privkey.pem files should appear in the /opt/certwardenclient/certs folder.

5. Mount them in the node’s docker-compose.yml (its web server is also called remnawave-nginx):

   cd /opt/remnanode && nano docker-compose.yml

   docker-compose.yml

   volumes:
     - /opt/certwardenclient/certs/fullchain.pem:/etc/nginx/ssl/yourdomain.com/fullchain.pem
     - /opt/certwardenclient/certs/privkey.pem:/etc/nginx/ssl/yourdomain.com/privkey.pem

6. Restart the node’s nginx:

   cd /opt/remnanode && docker compose down remnawave-nginx && docker compose up -d remnawave-nginx

Closing access to Certwarden with Netbird

Note

If you want to close access to Certwarden with Netbird, follow these steps

1. Add the Cert Warden server to Netbird, as its installation can be seen here

2. In the Cloudflare control panel for your domain certwarden.yourdomain.com, specify the IP address of the Cert Warden server in the Netbird network

   

3. Now, to access the Cert Warden page, you will need to connect to your network on your computer through the Netbird application

Clients must be in the NetBird network too

The Cert Warden client connects to the server by the certwarden.yourdomain.com domain itself. When the domain points to an IP in the NetBird network, every server running a client must be connected to NetBird too, otherwise the client cannot fetch the certificate.