For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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:


Using a self-signed certificate (internal / testing)

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

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:

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.

Last updated