TLS / HTTPS Setup

Enabling TLS is strongly recommended whenever maxmind-api-proxy is reachable by clients over a network, since the API_KEY header and MaxMind responses would otherwise travel in plaintext.

---

Enabling TLS

Set the following fields in your config file:

{
  "http_tls":  true,
  "http_cert": "/path/to/fullchain.pem",
  "http_key":  "/path/to/privkey.pem",
  "http_listen": ":8443"
}

Field	Description
http_tls	Must be true to activate TLS.
http_cert	Absolute path to the certificate file in PEM format. For Let's Encrypt this is fullchain.pem.
http_key	Absolute path to the private key file in PEM format. For Let's Encrypt this is privkey.pem.

The proxy uses Go's standard net/http TLS stack, which supports TLS 1.2 and 1.3.

---

Using Let's Encrypt (Certbot)

Certbot is the most common way to obtain free, auto-renewing TLS certificates.

Install and obtain a certificate

# Debian / Ubuntu
sudo apt install certbot

# Obtain a certificate (standalone mode — stop any web server first)
sudo certbot certonly --standalone -d yourproxy.example.com

Certbot stores certificates under /etc/letsencrypt/live/<domain>/. Update your config:

{
  "http_cert": "/etc/letsencrypt/live/yourproxy.example.com/fullchain.pem",
  "http_key":  "/etc/letsencrypt/live/yourproxy.example.com/privkey.pem"
}

Certificate renewal

Certbot installs a systemd timer or cron job that renews certificates automatically. After renewal the proxy must be restarted for it to load the new certificate:

# Add a renewal hook to restart the proxy after each renewal
echo "systemctl restart maxmind-api-proxy" > /etc/letsencrypt/renewal-hooks/deploy/restart-proxy.sh
chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-proxy.sh

---

Using a self-signed certificate (internal / testing)

For internal networks where you control the CA trust, you can generate a self-signed certificate:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
  -keyout proxy.key \
  -out proxy.crt \
  -subj "/CN=maxmind-proxy" \
  -addext "subjectAltName=IP:192.168.1.10,DNS:proxy.internal"

Then set http_cert to proxy.crt and http_key to proxy.key. Clients querying with curl will need -k (or --insecure) unless the certificate is added to their trust store.

---

Running without TLS

For localhost-only deployments or environments where TLS is terminated upstream (e.g. nginx, HAProxy, a cloud load balancer), you can run the proxy without TLS:

{
  "http_tls":    false,
  "http_listen": "127.0.0.1:8080",
  "http_cert":   "unused",
  "http_key":    "unused"
}

The config parser requires http_cert and http_key to be non-empty strings even when http_tls is false. Supply any non-empty placeholder value.