Add documentation for API reference, configuration, and self-hosting

2026-02-27 01:40:12 +00:00 · 2026-02-24 18:23:18 -05:00
parent 247f81d616
commit 605e9dca5d
3 changed files with 420 additions and 0 deletions
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -0,0 +1,119 @@
+# Configuration
+
+All server configuration is done via environment variables or a `.env` file in the project root.
+
+## Example .env
+
+```env
+PORT=8080
+API_KEY=your-secret-api-key
+CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
+LOG_FORMAT=json
+```
+
+Copy `.env.example` to get started:
+
+```bash
+cp .env.example .env
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Required | Description |
+|---|---|---|---|
+| `PORT` | `8080` | No | Port the HTTP server listens on. |
+| `API_KEY` | — | No* | Shared secret for API key auth. Auth is disabled when empty — do not leave empty in production. |
+| `CORS_ORIGINS` | `http://localhost:3000` | No | Comma-separated list of allowed CORS origins. |
+| `LOG_FORMAT` | `text` | No | `text` for human-readable, `json` for structured logging (recommended for production). |
+
+---
+
+## API Key Authentication
+
+The Go server uses a shared API key. This is intentional: the server is an internal service called only by the Next.js backend, not directly by end users.
+
+When `API_KEY` is set, every request (except `GET /health`) must include:
+
+```
+X-API-Key: your-secret-api-key
+```
+
+Requests with a missing or incorrect key get `401 UNAUTHORIZED`:
+
+```json
+{
+  "error": "missing or invalid API key",
+  "code": "UNAUTHORIZED"
+}
+```
+
+### Calling from Next.js
+
+```typescript
+const res = await fetch(`${process.env.DNS_SERVER_URL}/api/v1/dns/lookup`, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "X-API-Key": process.env.DNS_API_KEY!,
+  },
+  body: JSON.stringify({ domain, types }),
+});
+```
+
+Store `DNS_API_KEY` as a secret environment variable in your Next.js deployment. Never expose it client-side.
+
+---
+
+## CORS
+
+CORS is handled by [go-chi/cors](https://github.com/go-chi/cors). Configure allowed origins via `CORS_ORIGINS`.
+
+```env
+# Development
+CORS_ORIGINS=http://localhost:3000
+
+# Production (single domain)
+CORS_ORIGINS=https://app.yourdomain.com
+
+# Production (multiple domains)
+CORS_ORIGINS=https://app.yourdomain.com,https://yourdomain.com
+```
+
+Since the Go server is an internal API called server-side by Next.js, CORS is mostly relevant for development. In production, only your Next.js server IP/domain needs access.
+
+---
+
+## Rate Limiting
+
+Rate limiting is provided by [go-chi/httprate](https://github.com/go-chi/httprate) and is enabled by default.
+
+- Rate limiting is applied per IP address.
+- Limits are enforced at the router middleware level.
+- Requests exceeding the limit receive `429 Too Many Requests`.
+
+### Per-API-key rate limiting (planned)
+
+When billing tiers are added, rate limits will be enforced per API key:
+
+| Tier | Limit |
+|---|---|
+| Free | Limited requests per day, daily checks |
+| Pro | Higher limits, hourly checks |
+| Team | Highest limits, shared across org |
+
+---
+
+## Redis Caching (planned)
+
+DNS result caching via Redis is on the roadmap. When available, the server will check Redis before querying upstream DNS, storing results with TTL-based expiry.
+
+Planned configuration:
+
+```env
+REDIS_URL=redis://localhost:6379
+REDIS_TTL=300  # seconds
+```
+
+The cache layer will use [go-redis](https://github.com/redis/go-redis) as middleware before DNS resolution. A `docker-compose.yml` bundling the Go server with Redis will be provided for self-hosting. See [self-hosting.md](./self-hosting.md) for the planned compose configuration.