Docker Compose — Raspberry Pi¶

Dreadnought runs well on a Raspberry Pi. It's a great use case: low power, always on, sitting behind your home router with a dynamic IP.

This guide covers Pi-specific setup and gotchas on top of the standard Linux guide.

Supported Models¶

Dreadnought has been tested and works on:

Model	Architecture	RAM	Notes
Raspberry Pi 4 (2GB+)	ARM64	2–8GB	Recommended. Smooth experience.
Raspberry Pi 3B/3B+	ARM64/ARM32	1GB	Works fine. Slightly slower build.
Raspberry Pi Zero 2 W	ARM64	512MB	Works, but tight on RAM during build.
Raspberry Pi 5	ARM64	4–8GB	Works great.

Pi Zero (v1) is not supported. It uses a 32-bit ARMv6 processor, and the Node.js 18 base image requires ARMv7 or newer.

Prerequisites¶

Raspberry Pi with Raspberry Pi OS (64-bit) or Ubuntu Server 22.04 for Pi
Docker installed
SSH access or a keyboard/monitor connected
A Cloudflare API token — see Cloudflare Setup

Step 1 — Install Docker on Raspberry Pi OS¶

# Update system packages first
sudo apt update && sudo apt upgrade -y

# Install Docker using the official script
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group
sudo usermod -aG docker $USER

# Apply without re-logging in
newgrp docker

# Verify
docker --version
docker compose version

If you're on Ubuntu Server for Pi, this is the same process. Docker's install script handles Raspberry Pi automatically.

Step 2 — Clone the Repository¶

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

A good location on a Pi:

# Home directory
cd ~
git clone https://github.com/dreadnought-0/Dreadnought-DDNS.git
cd Dreadnought-DDNS

# Or in /opt for a more "server-like" layout
sudo mkdir -p /opt/dreadnought
sudo chown $USER:$USER /opt/dreadnought
cd /opt/dreadnought
git clone https://github.com/dreadnought-0/Dreadnought-DDNS.git .

Step 3 — Configure Environment¶

cp .env.sample .env
nano .env

CF_API_TOKEN=your_cloudflare_api_token_here
ADMIN_EMAIL=you@example.com
ADMIN_PASSWORD=a-strong-password

# Generate: openssl rand -hex 32
SECRET_KEY=paste-your-64-char-hex-key-here

POLL_INTERVAL_SECONDS=300
IPV6_ENABLED=false
DISCORD_WEBHOOK_URL=
TZ=America/New_York

Generate a SECRET_KEY on the Pi:

openssl rand -hex 32

Step 4 — Prepare the Data Directory¶

mkdir -p ./data
chmod 777 ./data

Or use the helper script:

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

Step 5 — Build and Start (First Run)¶

The first build will take longer on a Pi than on a server — expect 5–15 minutes depending on the model and SD card speed.

docker compose up -d

Watch the build progress:

docker compose logs -f

If you have a Pi 3 or Zero 2 W with limited RAM and the build seems to stall or fail, you may need to increase swap space temporarily:

# Increase swap to 1GB
sudo dphys-swapfile swapoff
sudo sed -i 's/CONF_SWAPSIZE=.*/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

# Try the build again
docker compose up -d --build

Step 6 — Access the Dashboard¶

From a browser on your local network, go to:

http://raspberrypi.local:8082

Or use the Pi's IP address directly:

http://192.168.1.x:8082

Find your Pi's IP with: hostname -I

Step 7 — Make It Persistent Across Reboots¶

The restart: unless-stopped policy in docker-compose.yml handles this automatically once Docker is configured to start at boot:

sudo systemctl enable docker

After this, Dreadnought starts automatically after every Pi reboot.

Setting Up for Remote Access (HTTPS)¶

Since the Pi is behind your home router, you have a few options:

Option A — Port Forward + Dynamic DNS (most common)¶

This is essentially what Dreadnought itself helps you with!

Log in to your home router's admin panel
Set up port forwarding: external port 443 → Pi's IP:443
Set up a reverse proxy on the Pi (see below)
Dreadnought keeps the DNS record pointing to your home IP

Option B — Tailscale (no port forwarding needed)¶

Tailscale creates a private network between your devices. Install it on the Pi and your other devices, and access the Pi via its Tailscale IP without any router changes.

# Install Tailscale on the Pi
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Then access Dreadnought at http://100.x.x.x:8082 (your Pi's Tailscale IP).

Option C — Cloudflare Tunnel¶

Cloudflare Tunnel (cloudflared) creates an outbound tunnel from the Pi to Cloudflare, so you don't need to open any firewall ports. See Cloudflare Tunnel docs.

Option D — Add a Reverse Proxy on the Pi¶

Install Nginx or Caddy on the Pi itself to handle TLS:

Nginx guide
Caddy guide — easiest for automatic HTTPS with Cloudflare DNS challenge

Pi-Specific Tips¶

Use an SSD Instead of a Micro SD Card¶

SD cards have limited write endurance. SQLite writes happen on every sync. For long-term reliability, boot from a USB SSD instead of a micro SD card. Pi 4 supports USB boot natively. Pi 3 requires a bootloader update.

Monitor SD Card Health¶

If you do use a micro SD card:

# Check for filesystem errors
sudo dmesg | grep -i "mmc\|mmcblk\|sd"

Keep the Pi Cool¶

If running in a case, make sure there's airflow. A Pi 4 under sustained load can throttle without cooling.

Reduce Docker Log Size¶

Docker logs can grow over time:

# Edit Docker daemon config
sudo nano /etc/docker/daemon.json

Add:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

sudo systemctl restart docker

Backup the Database¶

The entire application state lives in ./data/ddns.db. Back it up regularly:

# Manual backup
cp ./data/ddns.db ./data/ddns_backup_$(date +%Y%m%d).db

# Automated daily backup via cron (runs at 2 AM)
crontab -e
# Add this line:
0 2 * * * cp /home/pi/Dreadnought-DDNS/data/ddns.db /home/pi/Dreadnought-DDNS/data/ddns_$(date +\%Y\%m\%d).db

See Backup & Restore for more options.

Updating on Raspberry Pi¶

cd ~/Dreadnought-DDNS   # or wherever you cloned it

git pull origin main

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

The rebuild on a Pi takes several minutes. Your database and settings are preserved.

Troubleshooting Pi-Specific Issues¶

Build fails with "no space left on device"¶

# Check disk space
df -h

# Clean up Docker
docker system prune -af

# If running from SD card, consider moving to an external drive

Container crash with "cannot allocate memory"¶

Pi 3 / Zero 2 W with 1GB RAM can run tight during the Next.js build phase:

# Increase swap temporarily (see Step 5 above)
# Then rebuild
docker compose up -d --build

"exec format error" when running containers¶

You're likely on a 32-bit OS on a 64-bit Pi. Switch to Raspberry Pi OS (64-bit) or Ubuntu Server 22.04 for Pi.

Containers restart frequently¶

Check logs for the crashing container:

docker compose logs api --tail 50

Low memory can cause containers to be OOM-killed. Check:

dmesg | grep -i "oom\|killed"