mxlit/cloudflare-dns-gui repository overview

⁠Cloudflare DNS GUI & DDNS

A self-hosted, highly secure GUI and Dynamic DNS (DDNS) updater for your Cloudflare zones. Built with Zero Trust principles in mind.

⁠Features

• Action-Based MFA (Step-up Auth): Modifying or deleting records requires a live OTP code (Google Authenticator/Authy).
• Least Privilege (PoLP): Only visualizes and allows editing of 'A' and 'CNAME' records. Critical records like 'TXT' and 'MX' are filtered and protected from accidental deletion.
• Built-in DDNS: Mark any record to be "Monitored" and the server will automatically update it with your dynamic public IP.
• Hardened Session: Strict 5-minute cookie expiration.
• Brute-Force Protection: Built-in rate limiting and a 3-strike MFA kill-switch that destroys the session.
• Non-Root Container: Runs natively as an unprivileged 'node' user.

⁠Quick Start

⁠Option 1: Docker Compose (Recommended for Production)

The most secure method to prevent your passwords from being logged in your terminal history is to use Docker Compose with a '.env' file.

1. Create a file named '.env' with your secrets:

API_TOKEN=your_cloudflare_restricted_api_token
PASSWORD=your_secure_master_password

1. Create a 'docker-compose.yml' file:

services:
  cloudflare-dns-gui:
    image: mxlit/cloudflare-dns-gui:latest
    container_name: cloudflare-dns-gui
    ports:
      - "3000:3000"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
    restart: unless-stopped

1. Run it:

docker compose up -d

⁠Option 2: Docker Run (Quick Start)

If you prefer a single command (Warning: your secrets will be saved in your terminal's history file), you can pass them via '-e' flags:

docker run -d \
  --name cloudflare-dns-gui \
  -p 3000:3000 \
  -e API_TOKEN="your_cloudflare_restricted_api_token" \
  -e PASSWORD="your_secure_master_password" \
  -v /path/to/your/data:/app/data \
  --restart unless-stopped \
  mxlit/cloudflare-dns-gui:latest

⁠Environment Variables

• API_TOKEN: Create this in Cloudflare. It only needs 'Zone.DNS' (Edit) permissions for your specific zones.
• PASSWORD: The master password to log into the web interface.

⁠Volumes

• '/app/data': Stores your 'monitored.json' (DDNS targets) and 'mfa.json' (your OTP secret).

⁠MFA Setup

1. Log into the panel with your 'PASSWORD'.
2. On your first login, a QR code will be displayed.
3. Scan it with your Authenticator app.
4. Input the code to verify. From then on, all destructive actions will require a token.