Manage Certificates

Obtain and auto-renew SSL/TLS certificates with Aralez

🔐 Native Let’s Encrypt Integration

Since version v0.92.4, Aralez supports automatic ordering and renewal of SSL/TLS certificates using Let’s Encrypt via the HTTP-01 challenge.

Configuration

Aralez includes a built-in API server that responds to HTTP-01 challenges. This endpoint must be publicly accessible for your domain.

Update your upstreams.yaml:

your.domain.com:
  paths:
    "/":
      servers:
        - "192.168.1.1:8000"
        - "192.168.1.2:8000"
        - "192.168.1.3:8000"
    "/.well-known/acme-challenge":
      servers:
        - "127.0.0.1:3000"

This ensures Let’s Encrypt can reach:

http://your.domain.com/.well-known/acme-challenge/<token>

📜 Register and Obtain Certificates

Register (run once)

curl -H 'x-api-key: MASTER_KEY_FROM_MAIN_CONFIG' http://127.0.0.1:3000/acme_create

Request a Certificate

curl -H 'x-api-key: MASTER_KEY_FROM_MAIN_CONFIG' http://127.0.0.1:3000/acme_order/your.domain.com

Generated Files

Certificates are stored in:

CONFIG_DIR/autoconfigs/

Aralez automatically reloads certificates when they are updated. Renewal is triggered ~30 days before expiration.

🔐 Using Lego (Advanced / DNS Support)

Lego is an external ACME client that supports additional providers and DNS challenges.

Step 1: Configure Aralez

In main.yaml:

proxy_configs: /path/to/config/folder/

In upstreams.yaml:

myhost.mydomain.com:
  paths:
    "/":
      servers:
        - "127.0.0.1:8000"
    "/.well-known/acme-challenge":
      healthcheck: false
      servers:
        - "127.0.0.1:8899"

Step 2: Install Lego

Download from: https://github.com/go-acme/lego/releases

chmod +x lego
sudo mv lego /usr/local/bin/

Step 3: Request Certificates

lego   --key-type rsa2048   --domains="site1.example.com"   --email="your@email.com"   --accept-tos   --http.port=127.0.0.1:8899   --http run

Certificates will be stored in:

./.lego/certificates/

Step 4: Prepare Certificates for Aralez

cat ./.lego/certificates/site1.example.com*.crt > /path/to/certs/example.com.crt
cat ./.lego/certificates/site1.example.com.key > /path/to/certs/example.com.key

Step 5: Auto Reload

Aralez automatically reloads certificates without restart.

Expected naming:

example.com.crt
example.com.key

Step 6: Renewal Script

#!/bin/bash

lego --http renew

cat ./.lego/certificates/site1.example.com*.crt > /path/to/certs/example.com.crt
cat ./.lego/certificates/site1.example.com.key > /path/to/certs/example.com.key

Add to cron:

0 9 * * * /path/to/script.sh

🔁 Using ZeroSSL

Replace ACME server:

lego   --server "https://acme.zerossl.com/v2/DV90"   --eab   --kid "$KID"   --hmac "$HMAC"   --http run

✅ Summary