DNS Management

Overview

The infrastructure uses Cloudflare DNS for domain management with automatic SSL certificate provisioning through Traefik. All services are exposed as subdomains under *.rbnk.uk.

DNS Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Cloudflare DNS                           │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ Zone: rbnk.uk                                       │    │
│  │                                                     │    │
│  │ A Records (Proxied):                               │    │
│  │ - supabase.rbnk.uk    → 157.180.63.15             │    │
│  │ - litellm.rbnk.uk     → 157.180.63.15             │    │
│  │ - gitea.rbnk.uk       → 157.180.63.15             │    │
│  │ - metube.rbnk.uk      → 157.180.63.15             │    │
│  │ - paperless.rbnk.uk   → 157.180.63.15             │    │
│  │ - paperless-ai.rbnk.uk → 157.180.63.15            │    │
│  │ - *.rbnk.uk          → 157.180.63.15              │    │
│  │                                                     │    │
│  │ Benefits:                                           │    │
│  │ - DDoS Protection                                   │    │
│  │ - SSL Certificates                                  │    │
│  │ - CDN & Caching                                     │    │
│  │ - Security Features                                 │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                             │
                             │ HTTPS Traffic
                             ↓
                    ┌────────────────┐
                    │    Traefik     │
                    │ (Reverse Proxy)│
                    └────────────────┘

DNS Management Tools

The infrastructure provides two DNS management scripts with different capabilities:

1. Simple DNS Creation Tool

Location: /srv/dockerdata/_scripts/cloudflare-dns-create.sh

Purpose: Quick creation of A records for new services, primarily used by StackWiz

Usage:

# Basic usage (auto-detects server IP)
./cloudflare-dns-create.sh subdomain

# Specify record type and target
./cloudflare-dns-create.sh subdomain A 1.2.3.4

# Create record with auto-detected IP
./cloudflare-dns-create.sh myapp A AUTO

Features: - Simple A record creation - Auto-detection of server's public IP - Automatic proxying through Cloudflare - Integration with StackWiz for automated DNS during service creation - Falls back gracefully if API token unavailable

2. Advanced DNS Management Tool

Location: /srv/dockerdata/_scripts/cloudflare-dns.sh

Purpose: Full DNS management with support for all record types and operations

Usage:

# Make it easily accessible
sudo ln -s /srv/dockerdata/_scripts/cloudflare-dns.sh /usr/local/bin/cloudflare-dns

# Show help
cloudflare-dns --help

Features: - Create, update, delete, list, and get DNS records - Support for all DNS record types (A, AAAA, CNAME, MX, TXT, etc.) - Dedicated proxy command for easy Cloudflare proxy toggling - Update proxy status without changing record content - TTL management - Bulk operations and filtering - Interactive deletion confirmation

Common DNS Tasks

Creating DNS Records

A Record (IPv4)

# Simple A record with auto-detected IP
cloudflare-dns create A myapp AUTO

# Specific IP address
cloudflare-dns create A myapp 157.180.63.15

# Without Cloudflare proxy (direct connection)
cloudflare-dns create A myapp 157.180.63.15 --no-proxy

# With custom TTL (5 minutes)
cloudflare-dns create A myapp 157.180.63.15 --ttl 300

AAAA Record (IPv6)

cloudflare-dns create AAAA myapp 2001:db8::1

CNAME Record

# Point www to the main domain
cloudflare-dns create CNAME www myapp.rbnk.uk

# External CNAME
cloudflare-dns create CNAME blog external-blog.platform.com

MX Record (Mail)

# MX record with priority
cloudflare-dns create MX @ mail.server.com 10

# Multiple MX records with different priorities
cloudflare-dns create MX @ mail1.server.com 10
cloudflare-dns create MX @ mail2.server.com 20

TXT Record

# SPF record
cloudflare-dns create TXT @ "v=spf1 include:_spf.mail.com ~all"

# DMARC record
cloudflare-dns create TXT _dmarc "v=DMARC1; p=quarantine; rua=mailto:[email protected]"

# Domain verification
cloudflare-dns create TXT @ "google-site-verification=abc123..."

Listing DNS Records

# List all records
cloudflare-dns list

# Filter by type
cloudflare-dns list --type A
cloudflare-dns list --type TXT

# Filter by name
cloudflare-dns list --name myapp

# Show only proxied records
cloudflare-dns list --proxied

Getting Record Details

# Get all records for a subdomain
cloudflare-dns get myapp

# Get specific record type
cloudflare-dns get myapp A
cloudflare-dns get @ MX

Updating DNS Records

# Update IP address
cloudflare-dns update myapp 5.6.7.8

# Update with specific options
cloudflare-dns update myapp 5.6.7.8 --no-proxy --ttl 3600

# Update only proxy status (without changing IP)
cloudflare-dns update myapp --no-proxy
cloudflare-dns update myapp --proxy

# Update only TTL
cloudflare-dns update myapp --ttl 3600

# Update by record ID (for non-unique names)
cloudflare-dns update abc123def456 5.6.7.8

Managing Cloudflare Proxy

# Enable Cloudflare proxy (orange cloud)
cloudflare-dns proxy myapp on

# Disable Cloudflare proxy (gray cloud/DNS-only)
cloudflare-dns proxy myapp off

# Check current proxy status
cloudflare-dns get myapp | grep Proxied

Deleting DNS Records

# Delete by name (prompts for confirmation)
cloudflare-dns delete myapp

# Delete specific record type
cloudflare-dns delete myapp A

# Delete by record ID
cloudflare-dns delete abc123def456

Best Practices

1. Proxied vs. Direct Records

Use Proxied Records (Default) For: - Web services (HTTP/HTTPS) - APIs - Any service that benefits from DDoS protection - Services needing Cloudflare's security features

Use Direct Records (--no-proxy) For: - SSH access - Mail servers - Services requiring non-HTTP protocols - Services that need real client IPs

2. TTL Guidelines

• TTL 1 (Auto): Best for most cases, lets Cloudflare optimize
• TTL 300 (5 min): For records that might change soon
• TTL 3600 (1 hour): For stable records
• TTL 86400 (1 day): For very stable records

3. Naming Conventions

• Use descriptive subdomain names: api, app, admin, staging
• Avoid special characters except hyphens
• Keep subdomains short and memorable
• Use environment prefixes: staging-api, dev-app

4. Security Considerations

• Always proxy web services through Cloudflare
• Use TXT records for domain verification
• Implement SPF, DKIM, and DMARC for email
• Regularly audit DNS records with cloudflare-dns list

Integration with Services

StackWiz Integration

StackWiz automatically creates DNS records when deploying new services:

# Interactive mode prompts for DNS creation
stackwiz myapp

# Automatic DNS creation
stackwiz --create-dns myapp

# Skip DNS creation
stackwiz --no-dns myapp

Manual Service Deployment

When manually adding services:

1. Create the service (docker-compose.yml)
2. Add Traefik labels with the domain
3. Create DNS record:

   cloudflare-dns create A myservice AUTO
   

4. Start the service and verify access

Troubleshooting

DNS Not Resolving

# Check if record exists in Cloudflare
cloudflare-dns get myapp

# Check DNS propagation
dig myapp.rbnk.uk
dig @8.8.8.8 myapp.rbnk.uk
dig @1.1.1.1 myapp.rbnk.uk

# Check all nameservers
dig +trace myapp.rbnk.uk

SSL Certificate Issues

If SSL certificates aren't working:

1. Verify DNS record is proxied:

   cloudflare-dns get myapp
   # Should show "Proxied: Yes"
   

2. Check Cloudflare SSL mode (should be "Full" or "Full (strict)")

3. Verify Traefik labels include correct domain

Record Already Exists

# Check existing records
cloudflare-dns get myapp

# Update instead of create
cloudflare-dns update myapp NEW_IP

# Or delete and recreate
cloudflare-dns delete myapp
cloudflare-dns create A myapp NEW_IP

API Token Issues

If getting authentication errors:

1. Check token is set:

   # In environment
   echo $CF_API_TOKEN
   
   # Or in Traefik env file
   grep CF_DNS_API_TOKEN /srv/dockerdata/traefik/.env
   

2. Source from Traefik:

   source /srv/dockerdata/traefik/.env
   export CF_API_TOKEN=$CF_DNS_API_TOKEN
   

3. Use --token option:

   cloudflare-dns list --token YOUR_TOKEN
   

DNS Record Types Reference

Type	Purpose	Example
A	IPv4 address	myapp.rbnk.uk → 157.180.63.15
AAAA	IPv6 address	myapp.rbnk.uk → 2001:db8::1
CNAME	Alias to another domain	www.rbnk.uk → myapp.rbnk.uk
MX	Mail server	rbnk.uk → mail.server.com (priority: 10)
TXT	Text data	SPF, DMARC, verification
NS	Nameserver	Delegating subdomains
SRV	Service record	_service._proto.name → target:port
CAA	Certificate authority	Restrict who can issue SSL certs

Advanced Examples

Setting Up Email (MX + TXT)

# MX records
cloudflare-dns create MX @ mail.provider.com 10
cloudflare-dns create MX @ mail-backup.provider.com 20

# SPF record
cloudflare-dns create TXT @ "v=spf1 include:_spf.provider.com ~all"

# DMARC record
cloudflare-dns create TXT _dmarc "v=DMARC1; p=quarantine; rua=mailto:[email protected]"

# DKIM (get key from email provider)
cloudflare-dns create TXT default._domainkey "v=DKIM1; k=rsa; p=MIGfMA0..."

Setting Up Subdomain Delegation

# Delegate subdomain to different nameservers
cloudflare-dns create NS subdomain ns1.other-dns.com
cloudflare-dns create NS subdomain ns2.other-dns.com

Service Discovery (SRV)

# SRV record for service discovery
cloudflare-dns create SRV _service._tcp 0 5 8080 server.rbnk.uk

Automation

Bash Script for Bulk Operations

#!/bin/bash
# bulk-dns-create.sh

SERVICES=("app1" "app2" "api" "admin" "staging")

for service in "${SERVICES[@]}"; do
    echo "Creating DNS for $service..."
    cloudflare-dns create A "$service" AUTO
done

DNS Backup

# Export all DNS records
cloudflare-dns list > dns-backup-$(date +%Y%m%d).txt

# Parse for recreation script
cloudflare-dns list | grep "^A " | while read type name content proxy ttl; do
    echo "cloudflare-dns create $type $name $content"
done > recreate-dns.sh

When to Use Each Tool

Use cloudflare-dns-create.sh When:

• Deploying services with StackWiz
• Need quick A record creation only
• Working in automated scripts that only create records
• Want simple operation without many options

Use cloudflare-dns.sh When:

• Managing non-A record types (CNAME, MX, TXT, etc.)
• Need to update or delete existing records
• Want to list and audit DNS configuration
• Require advanced options (TTL, proxy control)
• Setting up email or other complex DNS configurations
• Need bulk operations or DNS management

Distribution and External Usage

The cloudflare-dns tool is now available as a standalone distribution package for use outside this infrastructure.

Distribution Package

Repository: https://gitea.rbnk.uk/admin/cloudflare-dns.git

The distribution includes: - Main cloudflare-dns script with all features - Quick installer for easy deployment - Docker support for containerized usage - Security utilities for credential management - Comprehensive documentation - Example configurations

Installation Methods

1. Quick Install Script

# Install to /usr/local/bin
curl -sSL https://gitea.rbnk.uk/admin/cloudflare-dns/raw/branch/main/install.sh | bash

# Or clone and install manually
git clone https://gitea.rbnk.uk/admin/cloudflare-dns.git
cd cloudflare-dns
./install.sh

2. Docker Container

# Build Docker image
git clone https://gitea.rbnk.uk/admin/cloudflare-dns.git
cd cloudflare-dns
docker build -t cloudflare-dns .

# Run with environment variables
docker run --rm \
  -e CF_API_EMAIL="[email protected]" \
  -e CF_DNS_API_TOKEN="your-api-token" \
  -e CF_ZONE_NAME="yourdomain.com" \
  cloudflare-dns list

3. Distribution Package

# Download pre-built package
wget https://gitea.rbnk.uk/admin/cloudflare-dns/releases/download/v1.0.0/cloudflare-dns-dist.tar.gz

# Extract and install
tar -xzf cloudflare-dns-dist.tar.gz
cd cloudflare-dns-dist
./install.sh

Configuration for External Use

1. Set Environment Variables:

   export CF_API_EMAIL="[email protected]"
   export CF_DNS_API_TOKEN="your-api-token"
   export CF_ZONE_NAME="yourdomain.com"
   

2. Or Create Config File:

   # ~/.cloudflare-dns/config
   CF_API_EMAIL="[email protected]"
   CF_DNS_API_TOKEN="your-api-token"
   CF_ZONE_NAME="yourdomain.com"
   

3. Secure Your Credentials:

   # Use the included security script
   ./scripts/cloudflare-dns-security.sh
   

Features in Distribution

• Full DNS Management: Create, update, delete, list all record types
• Proxy Control: Toggle Cloudflare proxy on/off
• Bulk Operations: Process multiple records efficiently
• Security Tools: Credential encryption and secure storage
• Cross-Platform: Works on Linux, macOS, BSD
• Minimal Dependencies: Only requires curl and jq
• Comprehensive Help: Built-in documentation and examples

Example Usage (External)

# After installation and configuration
cloudflare-dns create A app 1.2.3.4
cloudflare-dns proxy app on
cloudflare-dns list
cloudflare-dns update app 5.6.7.8
cloudflare-dns delete app

Related Documentation

• Adding Services - How DNS fits into service deployment
• StackWiz Guide - Automated DNS creation
• Traefik Configuration - How DNS relates to routing
• SSL/TLS Setup - Certificate management

---

Last Updated: July 2025