> For the complete documentation index, see [llms.txt](https://docs.k9.io/key9-identity/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.k9.io/key9-identity/maxmind-api-proxy/configuration/tls.md).

# 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:

```json
{
  "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](https://certbot.eff.org/) is the most common way to obtain free, auto-renewing TLS certificates.

### Install and obtain a certificate

```bash
# 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:

```json
{
  "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:

```bash
# 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:

```bash
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:

```json
{
  "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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.k9.io/key9-identity/maxmind-api-proxy/configuration/tls.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.