> 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/deployment/service.md).

# Running as a Service

For production use, run `maxmind-api-proxy` as a managed system service so that it starts automatically on boot and restarts on failure.

***

## Linux — systemd

### 1. Place the binary and config

```bash
# Copy the binary
sudo cp maxmind-api-proxy /usr/local/bin/maxmind-api-proxy
sudo chmod 755 /usr/local/bin/maxmind-api-proxy

# Create a config directory and copy the config
sudo mkdir -p /etc/maxmind-api-proxy
sudo cp my-config.json /etc/maxmind-api-proxy/config.json

# Restrict config permissions (contains credentials)
sudo chmod 600 /etc/maxmind-api-proxy/config.json
```

### 2. Create a dedicated service user

Running the proxy as a non-root user limits the blast radius if it is ever compromised.

```bash
sudo useradd --system --no-create-home --shell /usr/sbin/nologin maxmind-proxy
sudo chown root:maxmind-proxy /etc/maxmind-api-proxy/config.json
```

> If using TLS with Let's Encrypt, the service user also needs read access to the certificate files:
>
> ```bash
> sudo setfacl -m u:maxmind-proxy:rx /etc/letsencrypt/live/ /etc/letsencrypt/archive/
> ```

### 3. Create the unit file

Create `/etc/systemd/system/maxmind-api-proxy.service`:

```ini
[Unit]
Description=MaxMind API Proxy
After=network.target redis.service
Wants=redis.service

[Service]
Type=simple
User=maxmind-proxy
Group=maxmind-proxy
ExecStart=/usr/local/bin/maxmind-api-proxy /etc/maxmind-api-proxy/config.json
Restart=on-failure
RestartSec=5s

# Harden the service
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
```

### 4. Enable and start

```bash
sudo systemctl daemon-reload
sudo systemctl enable maxmind-api-proxy
sudo systemctl start maxmind-api-proxy

# Check status
sudo systemctl status maxmind-api-proxy

# Follow logs
sudo journalctl -u maxmind-api-proxy -f
```

### 5. Reload after config changes

The proxy reads its config only at startup. After editing the config file, restart the service:

```bash
sudo systemctl restart maxmind-api-proxy
```

***

## macOS — launchd

### 1. Place the binary and config

```bash
sudo cp maxmind-api-proxy /usr/local/bin/maxmind-api-proxy
sudo chmod 755 /usr/local/bin/maxmind-api-proxy

sudo mkdir -p /etc/maxmind-api-proxy
sudo cp my-config.json /etc/maxmind-api-proxy/config.json
sudo chmod 600 /etc/maxmind-api-proxy/config.json
```

### 2. Create the plist

Create `/Library/LaunchDaemons/io.k9.maxmind-api-proxy.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>io.k9.maxmind-api-proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/maxmind-api-proxy</string>
        <string>/etc/maxmind-api-proxy/config.json</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/maxmind-api-proxy.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/maxmind-api-proxy.log</string>
</dict>
</plist>
```

### 3. Load the service

```bash
sudo launchctl load /Library/LaunchDaemons/io.k9.maxmind-api-proxy.plist

# Check it is running
sudo launchctl list | grep maxmind
```

***

## Docker

A minimal `Dockerfile` for containerised deployments:

```dockerfile
FROM scratch
COPY maxmind-api-proxy /maxmind-api-proxy
COPY config.json /etc/maxmind-api-proxy/config.json
ENTRYPOINT ["/maxmind-api-proxy", "/etc/maxmind-api-proxy/config.json"]
```

Build and run:

```bash
# Cross-compile a static Linux binary
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o maxmind-api-proxy

docker build -t maxmind-api-proxy:latest .

docker run -d \
  --name maxmind-api-proxy \
  --restart unless-stopped \
  -p 8443:8443 \
  maxmind-api-proxy:latest
```

For configuration management in Docker, mount the config file as a volume rather than baking it into the image:

```bash
docker run -d \
  --name maxmind-api-proxy \
  --restart unless-stopped \
  -p 8443:8443 \
  -v /etc/maxmind-api-proxy/config.json:/etc/maxmind-api-proxy/config.json:ro \
  maxmind-api-proxy:latest
```


---

# 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/deployment/service.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.