Self-Hosting

Run the VectorDNS Go server on your own VPS or infrastructure. The DNS API is a single stateless binary — no database required.

Prerequisites

Docker — Recommended. No Go toolchain needed on the host.
Go 1.22+ — Required only if building from source.
Port 8080 — Default port (configurable via PORT env var).

Docker (Recommended)

1. Clone the repository

git clone https://github.com/yourusername/vectordns-server.git
cd vectordns-server

2. Create your .env file

cp .env.example .env
nano .env

At minimum, set API_KEY and CORS_ORIGINS. See configuration.md for all options.

3. Build the Docker image

docker build -t vectordns-server .

4. Run the container

docker run -d -p 8080:8080 --env-file .env --name vectordns-server vectordns-server

5. Verify it's running

curl http://localhost:8080/api/v1/health
# {"status":"ok","version":"0.1.0"}

From Source

Requires Go 1.22+.

# Install dependencies
go mod tidy

# Configure environment
cp .env.example .env && nano .env

# Run
go run ./cmd/server

# Or build a binary
go build -o vectordns-server ./cmd/server
./vectordns-server

VPS Deployment

Reverse proxy with nginx

Serve the Go server behind nginx to add TLS and a clean domain path.

# /etc/nginx/sites-available/vectordns
server {
    listen 443 ssl;
    server_name api.yourdomain.com;

    location /api/ {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

systemd service (non-Docker)

Keep the server running across reboots without Docker.

# /etc/systemd/system/vectordns-server.service
[Unit]
Description=VectorDNS Go Server
After=network.target

[Service]
ExecStart=/opt/vectordns/vectordns-server
EnvironmentFile=/opt/vectordns/.env
Restart=on-failure
User=www-data

[Install]
WantedBy=multi-user.target

sudo systemctl enable vectordns-server
sudo systemctl start vectordns-server

docker-compose with Redis (planned)

Once Redis caching ships, a docker-compose setup will be provided:

# docker-compose.yml (planned)
services:
  server:
    build: .
    ports:
      - "8080:8080"
    env_file: .env
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

Security Checklist

Set a strong API_KEY — do not leave auth disabled in production.
Set CORS_ORIGINS to your exact frontend domain, not *.
Always run behind TLS (use Let's Encrypt via Certbot with nginx).
Rate limiting is enabled by default — keep it on.

2.7 KiB Raw Blame History