Configuration File Reference

maxmind-api-proxy is configured through a single JSON file whose path is passed as the first argument on the command line:

./maxmind-api-proxy /etc/maxmind-api-proxy/config.json

The proxy will exit with a fatal error if the file cannot be opened, if the JSON is malformed, or if any required field is missing or empty.

---

Full example

{
  "api_key": "YOUR_PROXY_SERVICE_API_KEY",
  "cache_errors": false,

  "http_listen": ":8443",
  "http_tls": true,
  "http_cert": "/etc/letsencrypt/live/yoursite.example.com/fullchain.pem",
  "http_key":  "/etc/letsencrypt/live/yoursite.example.com/privkey.pem",
  "http_mode": "release",

  "maxmind_username": "123456",
  "maxmind_password": "your_maxmind_license_key",
  "maxmind_url": "https://geoip.maxmind.com/geoip/v2.1/city/",

  "redis_host":       "127.0.0.1",
  "redis_port":       6379,
  "redis_password":   "your_redis_password",
  "redis_database":   "0",
  "redis_cache_time": 24
}

---

Field reference

Proxy authentication

Field	Type	Required	Description
api_key	string	Yes	The secret key clients must supply in the API_KEY HTTP header to use the proxy. Choose a long, random string.

---

HTTP server

Field	Type	Required	Description
http_listen	string	Yes	Address and port to listen on. Use :8443 to listen on all interfaces on port 8443, or 127.0.0.1:8080 to restrict to localhost.
http_tls	bool	Yes	Set to true to enable TLS. See TLS Setup.
http_cert	string	Yes	Path to the TLS certificate file (PEM). Required by the config parser even when http_tls is false; supply a placeholder path if not using TLS.
http_key	string	Yes	Path to the TLS private key file (PEM). Same note as http_cert.
http_mode	string	Yes	Logging/runtime mode. See Run Modes. Valid values: debug, release, test, production.

---

MaxMind upstream

Field	Type	Required	Description
maxmind_username	string	Yes	Your MaxMind account ID (numeric string). Found in your MaxMind account portal under My Account → Account Information.
maxmind_password	string	Yes	Your MaxMind license key.
maxmind_url	string	Yes	The MaxMind GeoIP2 API endpoint to query. The IP address is appended to this URL. Default: https://geoip.maxmind.com/geoip/v2.1/city/

Available MaxMind endpoints

MaxMind offers several precision web service databases. Swap maxmind_url depending on the data you need:

Database	URL
City (recommended)	https://geoip.maxmind.com/geoip/v2.1/city/
Country	https://geoip.maxmind.com/geoip/v2.1/country/
Insights	https://geoip.maxmind.com/geoip/v2.1/insights/

---

Redis cache

Field	Type	Required	Description
redis_host	string	Yes	Hostname or IP address of the Redis server.
redis_port	integer	Yes	Port Redis is listening on (typically 6379).
redis_password	string	Yes	Password for Redis authentication.
redis_database	string	Yes	Redis logical database index (e.g. "0").
redis_cache_time	integer	Yes	How long to cache each result, in hours. After this TTL expires Redis automatically removes the entry and the next query will hit MaxMind again.
cache_errors	bool	Yes	When true, error responses from MaxMind (responses containing an "error" field) are also stored in Redis and served from cache. When false (recommended), errors are not cached so transient failures don't get stuck.

---

Notes

• The config file is read once at startup. To apply changes, restart the process.

• Protect the config file with filesystem permissions (chmod 600) since it contains your MaxMind credentials and Redis password.