Skip to content

Usage Guide

A reference for everything you can do in the Dreadnought dashboard.

The dashboard has these main sections:

Section Purpose
Dashboard Overview of current IP, sync status, and record count
Domains Manage registered Cloudflare zones
Records Manage DNS records being tracked
Import Bulk import records from JSON
Audit Log Full history of sync activity
Settings Adjust runtime configuration

Domains

Adding a Domain

A "domain" in Dreadnought is a Cloudflare zone — the root domain (e.g. example.com) with its Zone ID.

  1. Go to Domains → Add Domain
  2. Enter:
  3. Domain Name: The root domain (e.g. example.com, mydomain.net)
  4. Zone ID: 32-character hex string from Cloudflare dashboard
  5. Click Save

The domain is now available when adding records.

Editing a Domain

  1. Go to Domains
  2. Click the edit button next to the domain
  3. Update the name or Zone ID
  4. Save

Note: Changing a domain name or Zone ID won't automatically update existing DNS records in Cloudflare. Records tracked under the old name are associated with the new name going forward.

Deleting a Domain

A domain can only be deleted if it has no tracked records. Delete all records under the domain first, then delete the domain.

Records

Adding a Record

  1. Go to Records → Add Record
  2. Fill in:
  3. Domain: Select from your registered domains
  4. Host: The subdomain prefix (see table below)
  5. Type: A (IPv4) or AAAA (IPv6)
  6. Proxied: Whether to enable Cloudflare's proxy
  7. TTL: Time-to-live in seconds (1 = Auto)
  8. Click Create

The record is synced to Cloudflare immediately.

Host values:

Host What it creates
@ Root record (example.com)
www www.example.com
vpn vpn.example.com
* Wildcard (*.example.com)

TTL guidance:

TTL When to use
1 (Auto) Dynamic DNS — let Cloudflare manage TTL
60 Very fast propagation, high API traffic
300 Good balance (5 minutes)
3600 Stable records, lower API traffic (1 hour)
86400 Very stable records (24 hours)

Proxied records always use TTL 300 regardless of your setting — this is Cloudflare's behavior.

Editing a Record

  1. Go to Records
  2. Click the edit button next to the record
  3. Modify the host, type, proxied status, or TTL
  4. Save

The record is immediately synced to Cloudflare with the updated settings (and your current IP).

Deleting a Record

  1. Go to Records
  2. Click the delete button
  3. You'll be asked whether to also delete the record from Cloudflare:
  4. Yes — removes the A/AAAA record from Cloudflare DNS
  5. No — stops tracking it in Dreadnought but leaves the record in Cloudflare as-is

Filtering Records

Use the filter/search controls at the top of the Records list to filter by domain or record type.

Manual Sync

To trigger an immediate sync of all records (without waiting for the next poll):

  1. Go to the Dashboard
  2. Click Sync Now (or similar)

This forces the worker to detect the current IP and update all tracked records.

Alternatively, call the API directly:

curl -X POST http://localhost:8081/api/sync \
  -H "Cookie: session=your-session-cookie"

Bulk Import

Bulk import lets you add many records at once from a JSON file. Useful when migrating from another DDNS tool or setting up a fresh system with many records.

Import Format

The import endpoint accepts a JSON array:

[
  {
    "domain": "example.com",
    "host": "vpn",
    "ip_version": 4,
    "ttl": 300,
    "proxied": false
  },
  {
    "domain": "example.com",
    "host": "@",
    "ip_version": 4,
    "ttl": 1,
    "proxied": true
  },
  {
    "domain": "example.com",
    "host": "www",
    "ip_version": 4,
    "ttl": 300,
    "proxied": true
  }
]

Field reference:

Field Required Values Notes
domain Yes Any registered domain name Must already be registered in Dreadnought
host Yes String @ for root, or subdomain name
ip_version Yes 4 or 6 4 = A record, 6 = AAAA record
ttl Yes 1–86400 1 = Auto
proxied Yes true / false Cloudflare proxy status

Running an Import

  1. Go to Import
  2. Paste your JSON array into the text area
  3. Use dry-run first:
  4. Keep "Dry run" checked
  5. Click Preview Import
  6. Review the results — it shows which records would be created, which would be skipped (already exist), and any errors
  7. When satisfied, uncheck "Dry run" and click Import Records

Import Results

Each record in the response shows one of: - created — record was added and synced to Cloudflare - skipped — a record with this FQDN and type already exists - error — something went wrong (shown with a message)

Audit Log

The audit log records every sync event with full details.

What's Logged

Event When it happens
bulk_sync Worker poll cycle completes
immediate_sync Manual sync or UI-triggered sync

Each log entry includes: - Timestamp (in your configured timezone) - Action type - Number of records checked/updated - Old and new IP addresses - Duration - Any errors

Interpreting Log Entries

Normal sync (IP unchanged):

bulk_sync | 5 records checked | IP 203.0.113.5 unchanged | 0.8s

IP change detected:

bulk_sync | 5 records updated | IP changed: 203.0.113.5 → 203.0.113.99 | 2.1s

Sync error:

bulk_sync | Error: Cloudflare API rate limit exceeded | Retry in 60s

Pagination

The audit log is paginated. Use the navigation controls to browse older entries.

Settings

The Settings page provides a UI to change runtime configuration. Changes here update the database and take effect on the next worker cycle.

Setting Effect
Poll Interval (seconds) How often the worker checks for IP changes. Range: 60–7200.
IPv6 Enabled Toggle IPv6 detection on/off. Restart the worker after changing this.
Discord Webhook URL Set or clear the Discord notification webhook

Note on NEXT_PUBLIC_API_URL: This variable is not changeable at runtime — it's baked into the frontend JavaScript bundle at build time. To change it, update docker-compose.yml and run docker compose up -d --build.

Changing Your Password

Currently, passwords can be updated by:

  1. Stopping the app
  2. Editing ADMIN_PASSWORD in your .env
  3. Restarting the app — the password is re-hashed and stored on startup
# Edit .env, update ADMIN_PASSWORD
nano .env

# Restart
docker compose restart api

Discord Notifications

When a Discord webhook is configured, you'll receive notifications for:

Event Notification
IP change detected Your old and new IPs, number of records updated
Record update failed Which record failed and the error message
Sync error Full error details
Unexpected system error Traceback for debugging

Setting up a Discord webhook: 1. In Discord, go to your server → the channel you want → Edit Channel → Integrations → Webhooks 2. Create a new webhook and copy the URL 3. Paste it in Dreadnought's Settings page or in your .env as DISCORD_WEBHOOK_URL