Skip to content

Docker Desktop Deployment

This guide covers running Dreadnought on Windows or macOS using Docker Desktop. This is ideal for: - Running Dreadnought on your personal computer - Testing before deploying to a server - Home use where you want a GUI

Prerequisites

Step 1 — Get the Code

Option A — Git (recommended):

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

Option B — Download ZIP: 1. Go to the GitHub repository 2. Click Code → Download ZIP 3. Extract the ZIP and open a terminal in that folder

Step 2 — Create Your Environment File

In the project folder, copy the sample:

Windows (Command Prompt):

copy .env.sample .env

Windows (PowerShell):

Copy-Item .env.sample .env

macOS / Linux terminal:

cp .env.sample .env

Now edit .env with a text editor (Notepad, VS Code, TextEdit, etc.):

CF_API_TOKEN=your_cloudflare_api_token_here
ADMIN_EMAIL=you@example.com
ADMIN_PASSWORD=ChangeThisPassword!
SECRET_KEY=paste-a-64-char-random-string-here
POLL_INTERVAL_SECONDS=300
IPV6_ENABLED=false
DISCORD_WEBHOOK_URL=
TZ=America/New_York

Generate a SECRET_KEY on Windows (PowerShell):

-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })

Generate a SECRET_KEY on macOS / Linux:

openssl rand -hex 32

Step 3 — Create the Data Directory

Docker Desktop on Windows and Mac can write to directories without the chmod 777 step needed on Linux. Just create the folder:

Windows (Command Prompt or PowerShell):

mkdir data

macOS terminal:

mkdir -p ./data

Note: On macOS, if you get permission errors, run chmod 777 ./data just like on Linux. This can happen if Docker Desktop's file sharing settings are restrictive.

Step 4 — Start the App

Open a terminal in the project folder and run:

docker compose up -d

Docker Desktop will: 1. Download the base images (Node, Python) — first run only 2. Build the three application images — takes 1–3 minutes 3. Start the containers

You can watch this happen in the Docker Desktop GUI under the Containers tab.

Step 5 — Verify It's Running

In the terminal:

docker compose ps

All three services (api, worker, web) should show as running.

In Docker Desktop GUI: 1. Open Docker Desktop 2. Click Containers in the left sidebar 3. You'll see a dreadnought-ddns group (or similar) with three containers 4. All should show a green status

Check logs in Docker Desktop: - Click on any container name - Click the Logs tab to see its output

Step 6 — Open the Dashboard

Open your browser and go to:

http://localhost:8082

Log in with the credentials from your .env file.

Step 7 — Add Your Domain and Records

See First Use for a step-by-step guide.

Accessing From Other Devices on Your Network

By default, the app is only accessible at localhost. To access it from your phone or another computer:

  1. Find your computer's local IP address:
  2. Windows: ipconfig in Command Prompt → look for "IPv4 Address"
  3. Mac: ifconfig or System Settings → Network

  4. Example: 192.168.1.50

  5. Access the dashboard at http://192.168.1.50:8082 from another device

  6. For API calls from a different device to work correctly, update NEXT_PUBLIC_API_URL in docker-compose.yml: ```yaml web: environment:

    • NEXT_PUBLIC_API_URL=http://192.168.1.50:8081 `` Then rebuild:docker compose up -d --build`

Stopping and Starting

Stop (containers pause, data preserved):

docker compose stop

Start again:

docker compose start

Stop and remove containers (data still preserved in ./data):

docker compose down

Start fresh after down:

docker compose up -d

Auto-Start on Boot

Docker Desktop can be configured to start automatically when you log in, and containers with restart: unless-stopped (which Dreadnought uses) will start automatically when Docker starts.

Enable Docker Desktop auto-start: 1. Open Docker Desktop 2. Go to Settings → General 3. Enable Start Docker Desktop when you sign in

Updating

# Pull latest code
git pull origin main

# Rebuild images and restart
docker compose up -d --build

# Clean up old layers (optional)
docker system prune -f

Common Issues on Docker Desktop

"Port already in use"

If port 8081 or 8082 is already used by something else:

# In docker-compose.yml, change the host ports:
api:
  ports:
    - "9081:8000"   # Use 9081 instead of 8081

web:
  ports:
    - "9082:3000"   # Use 9082 instead of 8082

Docker Desktop is slow or uses too much memory

Reduce resource limits in Docker Desktop: - Settings → Resources → Advanced - Lower CPU cores and memory limits

File permission errors (macOS)

chmod 777 ./data

Or in Docker Desktop → Settings → Resources → File Sharing — make sure your project folder is shared.

Container shows "Exited" or "Unhealthy"

Click the container in Docker Desktop and check the Logs tab, or run:

docker compose logs api
docker compose logs worker
docker compose logs web

See Troubleshooting for common error fixes.