mirror of
https://github.com/DevVoxel/vectordns-server.git
synced 2026-02-27 01:40:12 +00:00
120 lines
3.3 KiB
Markdown
120 lines
3.3 KiB
Markdown
# 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.
|