Skip to content

Quick Start

Get Dreadnought running in about five minutes. This guide takes the shortest path: Docker Compose on a Linux machine or Raspberry Pi, with the app accessible locally.

For other environments (Windows, Coolify, Portainer, Raspberry Pi with more detail) see the Deployment Guide.

Prerequisites

  • Docker and Docker Compose installed (install Docker)
  • A Cloudflare account with at least one domain
  • A terminal on the machine where Docker is running

Step 1 — Get a Cloudflare API Token

You need a token that lets Dreadnought read your zones and edit DNS records.

  1. Log in to Cloudflare
  2. Go to My Profile → API Tokens → Create Token
  3. Click Create Custom Token
  4. Set these permissions:
  5. Zone → Zone → Read
  6. Zone → DNS → Edit
  7. Under Zone Resources, select either All zones or pick specific zones
  8. Click Continue to summary → Create Token
  9. Copy the token now — you won't be able to see it again

Tip: Scoping the token to only the zones Dreadnought needs to manage is better security practice. See Cloudflare Setup for a detailed walkthrough with screenshots descriptions.

Step 2 — Clone the Repository

git clone https://github.com/dreadnought-0/Dreadnought-DDNS.git
cd Dreadnought-DDNS

Step 3 — Create Your Environment File

cp .env.sample .env

Open .env in your editor and fill in the required values:

# --- REQUIRED ---

# Cloudflare API token (from Step 1)
CF_API_TOKEN=your_cloudflare_api_token_here

# Login credentials for the web dashboard
ADMIN_EMAIL=you@example.com
ADMIN_PASSWORD=ChangeThisToSomethingStrong!

# Secret key for session tokens — MUST be random and unique
# Generate one: openssl rand -hex 32
SECRET_KEY=paste-a-long-random-string-here

# --- OPTIONAL (defaults are fine to start) ---

# How often to check for IP changes, in seconds (60–7200)
POLL_INTERVAL_SECONDS=300

# Set to true to also manage IPv6 AAAA records
IPV6_ENABLED=false

# Discord webhook URL — leave empty to disable notifications
DISCORD_WEBHOOK_URL=

# Timezone for log timestamps
TZ=America/Denver

Generate a strong SECRET_KEY:

# On Linux/Mac:
openssl rand -hex 32

# Or using Python (works anywhere):
python3 -c "import secrets; print(secrets.token_hex(32))"

Step 4 — Prepare the Data Directory

The app stores its SQLite database in ./data. Docker needs write access to this folder before it starts.

mkdir -p ./data
chmod 777 ./data

Or use the included setup script which does the same thing:

chmod +x setup.sh && ./setup.sh

Why is this step needed? Docker containers run as a non-root user (UID 1000). The ./data folder on your host needs to be writable by that user before the container can create the database file. Platforms like Coolify handle this automatically.

Step 5 — Start the App

docker compose up -d

This builds the images on first run (takes a minute or two) and starts three containers: - api — the backend - worker — the background IP monitor - web — the frontend dashboard

Check that everything started cleanly:

docker compose ps

You should see all three services as running or healthy. If anything is unhealthy, check Troubleshooting.

Watch the logs (optional):

docker compose logs -f

Press Ctrl+C to stop following logs (the app keeps running).

Step 6 — Open the Dashboard

Open your browser and go to:

http://localhost:8082

Log in with the ADMIN_EMAIL and ADMIN_PASSWORD you set in your .env.

Step 7 — Add Your First Domain

  1. Click Domains in the navigation
  2. Click Add Domain
  3. Enter your domain name (e.g. example.com)
  4. Enter the Cloudflare Zone ID for that domain
  5. Find it in Cloudflare: select your domain → Overview → right sidebar → Zone ID
  6. Click Save

Step 8 — Add a DNS Record

  1. Click Records in the navigation
  2. Click Add Record
  3. Select your domain from the dropdown
  4. Enter the Host:
  5. @ for the root domain (example.com)
  6. A subdomain name for a subdomain (e.g. vpn for vpn.example.com)
  7. Set Type to A (IPv4) or AAAA (IPv6)
  8. Choose whether to enable Proxied (Cloudflare orange-cloud)
  9. Click Create

The record is synced to Cloudflare immediately with your current public IP.

You're Done

The worker will now automatically update this record whenever your IP changes. The default check interval is every 5 minutes.

To verify it's working: - Check Dashboard to see your current detected IP - Check Audit Log to see sync history - Check your Cloudflare DNS records to confirm the A record has been set

Next Steps

Goal Where to go
Make it accessible from the internet with HTTPS Nginx, Traefik, or Caddy guide
Deploy on Raspberry Pi with more detail Raspberry Pi guide
Use Docker Desktop on Windows or Mac Docker Desktop guide
Use Coolify for automatic TLS Coolify guide
Set up Discord notifications Configuration Reference
Import records in bulk Usage Guide
Understand all config options Configuration Reference