TLS Configuration

This guide explains all TLS configuration options in ReadyStackGo - from self-signed certificates through custom certificates to Let’s Encrypt and reverse proxy scenarios.

Overview

ReadyStackGo supports various TLS/HTTPS configurations:

Option	Use Case	Complexity
Self-Signed	Development, testing, internal network	No configuration needed
Custom Certificate	Corporate CA, purchased certificates	File upload
Let’s Encrypt	Production environments with public domain	Domain validation
Reverse Proxy	Behind nginx, Traefik, HAProxy, etc.	Proxy-dependent

All settings are located under Settings → TLS / Certificates in the Web UI.

---

Self-Signed Certificate

What is a self-signed certificate?

A self-signed certificate is automatically generated by ReadyStackGo on first start. It encrypts the connection but is not signed by a trusted Certificate Authority (CA). Browsers will therefore show a security warning.

When to use?

• Local development - Encryption without CA setup
• Internal test systems - When security warnings are acceptable
• Docker development - Quick start without certificate configuration

How it works

1. On first start, ReadyStackGo checks if a certificate exists
2. If not, a self-signed certificate is automatically generated
3. The certificate is stored at /app/config/tls/selfsigned.pfx
4. Validity: 365 days

Reset to self-signed certificate

If you’ve uploaded a custom certificate and want to switch back to self-signed:

1. Navigate to Settings → TLS / Certificates
2. Click Configure Certificate
3. Select Reset to Self-Signed
4. Confirm the action
5. Restart ReadyStackGo to load the new certificate

---

Custom Certificate

When to use?

• Corporate CA - Internal Certificate Authority
• Purchased certificates - From a public CA (DigiCert, Comodo, etc.)
• Wildcard certificates - One certificate for multiple subdomains

Supported formats

ReadyStackGo accepts two certificate formats:

Format	Files	Typical Source
PFX/PKCS#12	Single .pfx/.p12 file with password	Windows export, IIS
PEM	Separate certificate and key files	Linux, OpenSSL, Let’s Encrypt

Step-by-step: Upload PFX certificate

1. Navigate to Settings → TLS / Certificates
2. Click Configure Certificate
3. Select Upload PFX Certificate
4. Choose the .pfx file
5. Enter the password (if any)
6. Click Upload
7. Restart ReadyStackGo

PFX without password

If your PFX has no password, leave the password field empty.

Step-by-step: Upload PEM certificate

1. Navigate to Settings → TLS / Certificates
2. Click Configure Certificate
3. Select Upload PEM Certificate
4. Paste the certificate file content (starts with -----BEGIN CERTIFICATE-----)
5. Paste the key file content (starts with -----BEGIN PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY-----)
6. Click Upload
7. Restart ReadyStackGo

Certificate chain

If you have a certificate chain (intermediate certificates), paste all certificates in the correct order in the certificate field: Server certificate first, then intermediate certificates.

Create certificate with OpenSSL

If you need a self-signed certificate with longer validity or specific settings:

# Generate key and certificate (10 years validity)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes \
  -subj "/CN=readystackgo.local"

# Convert to PFX (optional)
openssl pkcs12 -export -out certificate.pfx -inkey key.pem -in cert.pem

---

Let’s Encrypt

What is Let’s Encrypt?

Let’s Encrypt is a free, automated Certificate Authority. The certificates are trusted by all major browsers and valid for 90 days. ReadyStackGo renews them automatically.

Prerequisites

• Publicly reachable domain - Let’s Encrypt must be able to validate your domain
• DNS record - The domain must point to your server
• Port 80 or DNS access - Depending on challenge type

Challenge types

Let’s Encrypt uses challenges to verify that you control the domain:

Challenge	Requirement	Advantages
HTTP-01	Port 80 reachable	Simplest setup
DNS-01	DNS access	Wildcard support, no port 80 needed

Step-by-step: HTTP-01 Challenge

This method is easiest when ReadyStackGo is directly reachable from the internet.

Prerequisite: Port 80 must point to your server (not just port 443).

1. Navigate to Settings → TLS / Certificates
2. Click Configure Certificate
3. Select Let’s Encrypt
4. Enter the following data:
   • Domains: Your domain(s), e.g., rsgo.example.com
   • Email: For expiration notifications
   • Challenge Type: HTTP-01
5. Optional: Enable Use Staging for testing (no real certificates)
6. Click Request Certificate
7. Wait for validation (seconds to minutes)
8. Restart ReadyStackGo

Port 80 forwarding

If you use a reverse proxy, it must forward port 80 to ReadyStackGo for the HTTP-01 challenge to work.

Step-by-step: DNS-01 Challenge (Manual)

This method requires manual creation of DNS records but also works for wildcard domains.

1. Navigate to Settings → TLS / Certificates
2. Click Configure Certificate
3. Select Let’s Encrypt
4. Enter the following data:
   • Domains: Your domain(s), e.g., *.example.com
   • Email: For expiration notifications
   • Challenge Type: DNS-01
   • DNS Provider: Manual
5. Click Request Certificate
6. The UI shows you the required TXT records:

Name: _acme-challenge.example.com
Value: abc123xyz...

7. Create the TXT record at your DNS provider
8. Wait for DNS propagation (can take up to 24 hours)
9. Click Confirm DNS Challenge
10. Restart ReadyStackGo

Step-by-step: DNS-01 Challenge (Cloudflare)

With Cloudflare, DNS records are automatically created and deleted.

1. Create a Cloudflare API token:

   • Go to Cloudflare Dashboard → Profile → API Tokens
   • Click Create Token
   • Select Edit zone DNS as template
   • Restrict to your zone
   • Copy the token

2. Navigate to Settings → TLS / Certificates

3. Click Configure Certificate

4. Select Let’s Encrypt

5. Enter the following data:

   • Domains: Your domain(s)
   • Email: For expiration notifications
   • Challenge Type: DNS-01
   • DNS Provider: Cloudflare
   • Cloudflare API Token: The copied token
   • Cloudflare Zone ID: (Optional) Found in Cloudflare Dashboard under Overview

6. Click Request Certificate

7. Restart ReadyStackGo

Automatic Renewal

ReadyStackGo automatically renews Let’s Encrypt certificates:

• Check interval: Every 12 hours
• Renewal: 30 days before expiration
• Status: Visible under Settings → TLS

If automatic renewal fails:

1. Check the error under Settings → TLS
2. Ensure the challenge still works
3. For DNS-01 Manual: Create the new TXT record

Staging vs. Production

Let’s Encrypt has strict rate limits for production certificates. For testing:

1. Enable Use Staging
2. Test the complete configuration
3. Staging certificates are not trusted by browsers (warning)
4. Disable staging for the real certificate
5. Request a new certificate

---

Reverse Proxy Configuration

When to use?

When ReadyStackGo runs behind an edge proxy:

• nginx as reverse proxy
• Traefik for container routing
• HAProxy for load balancing
• Cloud Load Balancers (AWS ALB, Azure App Gateway, etc.)

SSL Handling Modes

ReadyStackGo supports three modes for SSL communication with the proxy:

SSL Termination

Client ──HTTPS──► Proxy ──HTTP──► ReadyStackGo

Description:

• The proxy terminates SSL and decrypts the traffic
• ReadyStackGo receives unencrypted HTTP traffic
• ReadyStackGo does not need a certificate

When to use:

• Proxy manages all certificates (e.g., Traefik with Let’s Encrypt)
• Simplest configuration
• Internal connection (proxy and ReadyStackGo in the same network)

Configuration:

1. Navigate to Settings → TLS / Certificates
2. Enable Reverse Proxy Mode
3. Select SSL Termination
4. Restart ReadyStackGo

Nginx Example:

server {
    listen 443 ssl;
    server_name rsgo.example.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://readystackgo:8080;
        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;
        proxy_set_header X-Forwarded-Host $host;
    }
}

SSL Passthrough

Client ──HTTPS──► Proxy ──HTTPS──► ReadyStackGo
        (encrypted passthrough)

Description:

• The proxy forwards encrypted traffic unchanged
• ReadyStackGo terminates SSL
• ReadyStackGo requires a certificate

When to use:

• End-to-end encryption required
• ReadyStackGo manages its own certificate
• Layer 4 load balancing (TCP proxy)

Configuration:

1. Configure a certificate in ReadyStackGo (self-signed, custom, or Let’s Encrypt)
2. Navigate to Settings → TLS / Certificates
3. Enable Reverse Proxy Mode
4. Select SSL Passthrough
5. Restart ReadyStackGo

Nginx Example (Stream Module):

stream {
    upstream readystackgo {
        server readystackgo:8443;
    }

    server {
        listen 443;
        proxy_pass readystackgo;
    }
}

Traefik Example:

traefik.yml

entryPoints:
  websecure:
    address: ":443"

# Dynamic config
tcp:
  routers:
    rsgo:
      rule: "HostSNI(`rsgo.example.com`)"
      service: rsgo
      tls:
        passthrough: true
  services:
    rsgo:
      loadBalancer:
        servers:
          - address: "readystackgo:8443"

Re-Encryption

Client ──HTTPS──► Proxy ──HTTPS──► ReadyStackGo
        (terminated)    (re-encrypted)

Description:

• The proxy terminates the client SSL connection
• The proxy creates a new SSL connection to ReadyStackGo
• Both sides need certificates

When to use:

• Compliance requires encrypted internal connections
• Zero-trust network
• Proxy and ReadyStackGo in different network segments

Configuration:

1. Configure a certificate in ReadyStackGo
2. Navigate to Settings → TLS / Certificates
3. Enable Reverse Proxy Mode
4. Select Re-Encryption
5. Restart ReadyStackGo

Self-signed for backend

With Re-Encryption, a self-signed certificate for ReadyStackGo is often sufficient since only the proxy needs to validate it. Configure the proxy to trust the backend certificate.

Nginx Example:

server {
    listen 443 ssl;
    server_name rsgo.example.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass https://readystackgo:8443;
        proxy_ssl_verify off;  # For self-signed backend certificate
        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;
        proxy_set_header X-Forwarded-Host $host;
    }
}

Forwarded Headers

With SSL Termination and Re-Encryption, ReadyStackGo automatically processes X-Forwarded-* headers:

Header	Description
X-Forwarded-For	Real client IP (important for logs and rate limiting)
X-Forwarded-Proto	Original protocol (http/https) for correct redirects
X-Forwarded-Host	Original hostname for URL generation

These headers are automatically trusted when reverse proxy mode is enabled.

Security note

Only enable reverse proxy mode if ReadyStackGo is actually behind a proxy. With direct internet access, spoofed headers can lead to security issues.

SSL Mode Comparison Table

Aspect	SSL Termination	SSL Passthrough	Re-Encryption
Certificate in ReadyStackGo	Not needed	Required	Required
Proxy certificate	Required	Not needed	Required
Traffic to backend	HTTP	HTTPS	HTTPS
Forwarded Headers	Yes	No	Yes
Proxy can read traffic	Yes	No	Yes
Configuration complexity	Low	Medium	Medium

---

Enable/Disable HTTP Port

ReadyStackGo can optionally also serve HTTP (unencrypted):

1. Navigate to Settings → TLS / Certificates
2. Enable or disable HTTP Enabled
3. Restart ReadyStackGo

HTTPS Redirect

When HTTP is enabled, requests to HTTP are automatically redirected to HTTPS - except in SSL Termination mode where backend traffic is already HTTP.

---

Troubleshooting

Certificate is not loaded

Problem: After upload, the old certificate is still shown.

Solution: ReadyStackGo must be restarted for the new certificate to be loaded.

Let’s Encrypt fails

Problem: “Failed to validate domain”

Possible causes:

1. HTTP-01: Port 80 not reachable
2. DNS-01: TXT record not created or not yet propagated
3. Domain not pointing to server: Check DNS record

Debug steps:

1. Check the error under Settings → TLS
2. Test port 80 reachability: curl http://yourdomain.com/.well-known/acme-challenge/test
3. Check DNS: dig TXT _acme-challenge.yourdomain.com

Browser shows security warning

With self-signed certificate: Expected. Use Let’s Encrypt or a CA certificate for production.

With Let’s Encrypt: Check if you’re in staging mode. Staging certificates are not trusted.

Proxy gets “Connection refused”

Problem: The reverse proxy cannot reach ReadyStackGo.

Check:

1. Is ReadyStackGo running? docker ps
2. Correct port? HTTP = 8080, HTTPS = 8443
3. Network connectivity? docker network ls

---

Related Links

• Installation - Install ReadyStackGo
• Stack Deployment - Deploy stacks