Quick Start

DNS Worker offers two deployment paths tailored to your needs. As a Serverless-First platform, deploying to Cloudflare Workers is the primary, recommended approach for zero-maintenance global edge resolution.

Method 1: Deploy to Cloudflare Workers (Serverless - Recommended)

Deploy across 300+ edge locations worldwide with automatic global failover and zero server patching.

1. Clone & Install Dependencies

git clone https://github.com/Obein/DNS-Worker.git
cd DNS-Worker
npm install

2. Create Cloudflare D1 Database

# Log in to Cloudflare via Wrangler CLI
npx wrangler login

# Create D1 database for DNS Worker
npm run db:setup

Copy the output database_id into wrangler.toml under [[d1_databases]]:

[[d1_databases]]
binding = "DB"
database_name = "dns_worker_db"
database_id = "your-database-id-here"

3. Initialize Database Schema & Deploy

# 1. Apply database migrations to production D1
npm run db:migrate:prod

# 2. Build Web Dashboard and deploy Worker
npm run deploy

Once deployed, your secure DNS resolution endpoint and Web Dashboard are live immediately at https://<your-worker>.workers.dev (or your custom apex domain).

Method 2: Standalone Server / VPS (Serverfull - Node.js / Bun)

If you require raw UDP port 53 for local home routers or dedicated Android Private DNS on port 853:

# 1. Install CLI globally (via npm or bun)
npm install -g dns-worker
# or: bun install -g dns-worker

# 2. Initialize persistent directory and default configuration
dns-worker config init

# 3. Start DNS Worker daemon (runs on Node.js >= 22.5 or Bun >= 1.4)
dns-worker

Access the local management dashboard at http://localhost:10080 and UDP DNS at 127.0.0.1:53.