Use Certbot with STACKIT DNS

This guide shows you how to leverage the DNS01 ACME challenge with Certbot. You will learn to:

Set up Certbot, Nginx, and the STACKIT Certbot plugin on an Ubuntu server.
Generate a wildcard certificate for a zone.
Point an A-record to the server IP.
Resolve the domain to display Nginx’s web content — all under SSL encryption.

Prerequisites

Ubuntu Server:
- Ensure you have access to an Ubuntu server, preferably with a public IP for internet accessibility. Though similar steps apply to other Linux distributions, this guide focuses on Ubuntu.
- For this tutorial, we are using a STACKIT Ubuntu VM setup based on this tutorial. Ensure port 22 (SSH), port 80 (HTTP traffic) and port 443 (SSL traffic) are open in the security group settings.
STACKIT DNS Zone: Have a configured zone, such as “certbot.runs.onstackit.cloud” for this guide.
Required Credentials: A service account and corresponding authentication service account key are necessary for the deployment process. Certbot will programmatically create and delete a temporary TXT-record in the DNS zone, requiring the service account to have DNS Admin permissions.

Implementation

Determine the server’s IP:
Terminal window
```
wget -qO- ifconfig.schwarz | xargs echo
```
You will get an output like that:
```
193.148.162.182
```
From here on the guide assumes, that your server’s IPv4 address is 193.148.162.182. Replace this address with your individual server’s IPv4 address.
Configure an A-record: Set up a wildcard A-Record pointing to your server’s IP. This ensures every subsequent record in the zone resolves to the Ubuntu server, showcasing the wildcard certificate’s utility.
Install Nginx with apt:
Terminal window
```
sudo apt update
sudo apt install nginx
```
Confirm Nginx is running:
Terminal window
```
curl http://193.148.162.182
```
If everything works you get an output like this:
```
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...
```
Nginx on Ubuntu 22.04 defaults to serving documents from /var/www/html. For multiple sites, it’s better to have separate directories. Instead of modifying /var/www/html, we’ll set up a separate structure.

Create a directory for app.certbot.runs.onstackit.cloud:

sudo mkdir -p /var/www/app.certbot.runs.onstackit.cloud/html

Create and edit index.html:

sudo vi /var/www/app.certbot.runs.onstackit.cloud/html/index.html

You get an output like the following:

<html>
    <head>
        <title>Welcome to app.certbot.runs.onstackit.cloud!</title>
    </head>
    <body>
        <h1>Success!</h1>
    </body>
</html>

Nginx Server Block Configuration: Create a new server block:

sudo vi /etc/nginx/sites-available/app.certbot.runs.onstackit.cloud

Insert the appropriate configuration. Ensure you’ve set the correct directory and domain name.

server {
        listen 80;
        listen [::]:80;
        # ssl block will be needed later
        # listen 443 ssl;

        # ssl on;
        # ssl_certificate /etc/letsencrypt/live/certbot.runs.onstackit.cloud/fullchain.pem;
        # ssl_certificate_key /etc/letsencrypt/live/certbot.runs.onstackit.cloud/privkey.pem;

        root /var/www/app.certbot.runs.onstackit.cloud/html;
        index index.html index.htm index.nginx-debian.html;

        server_name app.certbot.runs.onstackit.cloud www.app.certbot.runs.onstackit.cloud;

        location / {
                try_files $uri $uri/ =404;
        }
}

Activate the new configuration:

sudo ln -s /etc/nginx/sites-available/app.certbot.runs.onstackit.cloud /etc/nginx/sites-enabled/

Validate Nginx configurations:

sudo nginx -t

If no errors arise, restart Nginx:

sudo systemctl restart nginx

Test: Access http://app.certbot.runs.onstackit.cloud/ in your browser. If successful, you should view the site you’ve just set up.

Install Certbot: Up till now, our connection remains unsecured. To enhance security, we will deploy Certbot in conjunction with the STACKIT plugin.

sudo apt install python3 python3-venv
sudo python3 -m venv /opt/certbot/
sudo /opt/certbot/bin/pip install --upgrade pip
sudo /opt/certbot/bin/pip install certbot certbot-dns-stackit
sudo ln -s /opt/certbot/bin/certbot /usr/bin/certbot

Set Up Authentication Credentials: For Certbot to autonomously create a TXT record in the zone, it requires authentication. Create new or use existing service account key and download the service account JSON file, for example service-account.json. If you use a provided private key, the private key has to be added to the service-account.json file:

{
  "id": "*SERVICE_ACCOUNT_KEY_ID*",
  "publicKey": "*PUBLIC_KEY*",
  "createdAt": "2025-12-09T07:51:11.569+00:00",
  "keyType": "USER_MANAGED",
  "keyOrigin": "*GENERATED*",
  "keyAlgorithm": "RSA_2048",
  "active": true,
  "credentials": {
    "kid": "*SERVICE_ACCOUNT_KEY_ID*",
    "iss": "*SERVICE_ACCOUNT_EMAIL*",
    "sub": "*SERVICE_ACCOUNT_ID*",
    "aud": "https://stackit-service-account-prod.apps.01.cf.eu01.stackit.cloud",
    "privateKey": "*PRIVATE_KEY*"
  }
}

In case of a provided private key, the service-account.json does not contain the privateKey. The private key can be added with the following command (private-key.pem holds your provided private key, service-account.json is the downloaded service account JSON file without the private key):

jq ". | .credentials.privateKey = \"$(cat private-key.pem | sed 's/$/\\n/g' | tr -d '\n')\"" service-account.json > service-account-with-private-key.json

Generate Wildcard Certificate: Create a wildcard certificate for your zone:

sudo certbot certonly \
--authenticator dns-stackit \
--dns-stackit-project-id \ # your project id
--dns-stackit-service-account ./service-account.json \ # your service account json
--dns-stackit-propagation-seconds 300 \
--server https://acme-v02.api.letsencrypt.org/directory \
--agree-tos \
-d 'certbot.runs.onstackit.cloud' \
-d '*.certbot.runs.onstackit.cloud'

Once the command executes, Certbot begins creating a temporary TXT-record within the designated zone: Certbot created temporary TXT-records

Record Propagation: If the propagation is successful, Certbot will retract the temporary record. Wait for the process to complete, which could take up to 300 seconds or more. A successful outcome will be indicated with an appropriate message:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/certbot.runs.onstackit.cloud/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/certbot.runs.onstackit.cloud/privkey.pem
This certificate expires on 2023-12-26.
These files will be updated when the certificate renews.

NEXT STEPS:
- The certificate will need to be renewed before it expires. Certbot can automatically renew the certificate in the background, but you may need to take steps to enable that functionality. See https://certbot.org/renewal-setup for instructions.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
* Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
* Donating to EFF:                    https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

You can confirm the presence of the certificate on the machine using:

sudo certbot certificates

You get an output like this:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Found the following certs:
Certificate Name: certbot.runs.onstackit.cloud
    Serial Number: 3e826ad25e4a1ef87e91cfd1d34979bf412
    Key Type: ECDSA
    Domains: certbot.runs.onstackit.cloud *.certbot.runs.onstackit.cloud
    Expiry Date: 2023-12-26 13:23:19+00:00 (VALID: 90 days)
    Certificate Path: /etc/letsencrypt/live/certbot.runs.onstackit.cloud/fullchain.pem
    Private Key Path: /etc/letsencrypt/live/certbot.runs.onstackit.cloud/privkey.pem
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Enable SSL for Nginx: Uncomment the previously commented-out SSL configuration in the Nginx configuration file to activate SSL:

sudo vi /etc/nginx/sites-available/app.certbot.runs.onstackit.cloud

You get an output like the following:

server {
        listen 80;
        listen [::]:80;

        listen 443 ssl;

        ssl on;
        ssl_certificate /etc/letsencrypt/live/certbot.runs.onstackit.cloud/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/certbot.runs.onstackit.cloud/privkey.pem;

        root /var/www/app.certbot.runs.onstackit.cloud/html;
        index index.html index.htm index.nginx-debian.html;

        server_name app.certbot.runs.onstackit.cloud www.app.certbot.runs.onstackit.cloud;

        location / {
                try_files $uri $uri/ =404;
        }
}

Once the modifications are made, restart Nginx to implement the updated configuration:

sudo systemctl restart nginx

Testing the Secure Connection: With the certificate now in place, access https://app.certbot.runs.onstackit.cloud/ in your browser. The connection should be SSL-encrypted, ensuring a secure browsing experience.