Skip to Content
DocsFeaturesBuilt-in AppsOperationsMaintenance

Maintenance App - Simple Cloudflare Site Management

The Maintenance app provides a simple, efficient solution for managing maintenance mode across Cloudflare sites using Page Rules. Built with the KISS principle (Keep It Simple, Stupid), it focuses on core functionality without unnecessary complexity.

Overview

The Maintenance app includes:

  • 🌐 Multi-Site Management - Manage Cloudflare sites with simple ORM interface
  • ⚡ Page Rules Integration - Works with Cloudflare Free plan using Page Rules
  • 🔄 Bulk Operations - Enable/disable maintenance for multiple sites simultaneously
  • 📊 Clean Admin Interface - Django admin integration with Unfold styling
  • 📱 CLI Management - Simple management commands for automation
  • 📋 Audit Trail - Operation logging for transparency

Architecture

Core Models

# Essential Models (4 total)
CloudflareSite       # Site configuration with custom maintenance URLs
CloudflareApiKey     # API key management with automatic defaults
MaintenanceLog       # Operation audit trail
ScheduledMaintenance # Planned maintenance events

Service Layer

# Core Services (4 total)
MaintenanceService      # Page Rules based maintenance control
SiteSyncService        # Automatic site discovery from Cloudflare
BulkOperationsService  # Multi-site operations
ScheduledMaintenanceService # Maintenance scheduling

Management Commands

# CLI Commands (3 total)
maintenance                   # Site maintenance management
sync_cloudflare              # Site discovery and synchronization
process_scheduled_maintenance # Scheduled maintenance processor

Quick Start

Enable in Configuration

# config.py
from django_cfg import DjangoConfig
 
class MyProjectConfig(DjangoConfig):
    # Enable maintenance app
    enable_maintenance: bool = True

Environment Configuration

# config.dev.yaml
# No additional configuration needed!
# Just add your Cloudflare API token via admin interface

Run Migrations

python manage.py migrate

Add Cloudflare API Key

  1. Go to Django Admin: /admin/maintenance/cloudflareapikey/
  2. Add your Cloudflare API token
  3. Sites will be auto-discovered and synced

Site Management

Simple Interface

from django_cfg.apps.maintenance import CloudflareSite, MaintenanceService
 
# Get site
site = CloudflareSite.objects.get(domain='example.com')
 
# Enable maintenance
service = MaintenanceService(site)
log_entry = service.enable_maintenance("Database upgrade")
 
# Disable maintenance  
log_entry = service.disable_maintenance()
 
# Check status
is_active = service.get_status()

Custom Maintenance URLs

# Create site with custom maintenance page
site = CloudflareSite.objects.create(
    name="My Site",
    domain="example.com", 
    zone_id="zone_123",
    account_id="account_123",
    api_key=api_key,
    
    # Custom maintenance URL (optional)
    maintenance_url="https://status.mycompany.com/?site=example.com"
)
 
# If maintenance_url is empty, uses default:
# https://docs.djangocfg.com/maintenance?site=example.com

Subdomain Configuration

# Default: Include ALL subdomains (*.example.com)
site = CloudflareSite.objects.create(
    name="My Site",
    domain="example.com",
    api_key=api_key,
    include_subdomains=True,    # Default: True
    subdomain_list=""           # Default: empty
)
 
# Custom: Include SPECIFIC subdomains only
site = CloudflareSite.objects.create(
    name="My Site", 
    domain="example.com",
    api_key=api_key,
    include_subdomains=False,   # Disable wildcard
    subdomain_list="api,dashboard,www"  # Specific subdomains
)
 
# This will create Page Rules for:
# - api.example.com/*
# - dashboard.example.com/* 
# - www.example.com/*
# (root example.com/* is always included)

Bulk Operations

# Enable maintenance for multiple sites
sites = CloudflareSite.objects.filter(is_active=True)
results = CloudflareSite.objects.bulk_sync_all()
print(f"Synced: {results['synced']}, Errors: {results['errors']}")
 
# Discover new sites
results = CloudflareSite.objects.discover_all_sites()
print(f"Discovered: {results['created']} new sites")

CLI Management

Basic Commands

# Enable maintenance for specific domain
python manage.py maintenance enable example.com --reason "Database upgrade"
 
# Disable maintenance
python manage.py maintenance disable example.com
 
# Check status
python manage.py maintenance status example.com
 
# List all sites
python manage.py maintenance list

Site Discovery

# Sync sites from Cloudflare
python manage.py sync_cloudflare
 
# Force full sync
python manage.py sync_cloudflare --force
 
# Sync specific API key
python manage.py sync_cloudflare --api-key "My API Key"

Admin Interface

Site Management

The admin interface provides:

  • 📋 Site List - Overview with maintenance status badges
  • 🔄 Action Buttons - Individual site actions (sync, enable/disable maintenance)
  • 📈 Bulk Actions - Mass operations from the list view
  • 🔍 Filtering - Filter by maintenance status, API key, activity
  • 📝 Logs - Complete operation history

Available Actions

Individual Site Actions (Detail View)

  • 🔄 Sync with Cloudflare - Update site configuration
  • 🔧 Enable Maintenance - Put site in maintenance mode
  • ✅ Disable Maintenance - Remove maintenance mode

Bulk Actions (List View)

  • 🔄 Bulk Sync Sites - Sync multiple sites with Cloudflare
  • 🔍 Bulk Discover Sites - Discover new sites from Cloudflare

Accessing Admin

# Navigate to maintenance admin
http://localhost:8000/admin/maintenance/cloudflaresite/
 
# Individual actions available in site detail view
# Bulk actions available in site list view

How It Works

Page Rules Technology

The maintenance app uses Cloudflare Page Rules instead of Workers, making it compatible with Cloudflare Free plans:

  1. Enable Maintenance: Creates Page Rules that redirect domains to maintenance page
    • All Subdomains: *.domain.com/* + domain.com/* (if include_subdomains=True)
    • Specific Subdomains: Individual rules for each subdomain (if include_subdomains=False)
  2. Disable Maintenance: Finds and deletes all maintenance Page Rules for the site
  3. Custom URLs: Supports custom maintenance pages or uses default Django-CFG page
  4. Subdomain Support: Flexible configuration for subdomain handling

Automatic Discovery

from django_cfg.apps.maintenance.services import SiteSyncService
 
# Auto-discover zones from Cloudflare
api_key = CloudflareApiKey.objects.get_default()
sync_service = SiteSyncService(api_key)
 
# Discover and create/update sites
sites_data = sync_service.sync_zones()
print(f"Processed {len(sites_data)} zones")

What Gets Auto-Configured

  1. Zone Discovery - Finds all zones in Cloudflare account
  2. Site Creation - Creates Django models for each zone
  3. Configuration Sync - Updates zone_id, account_id automatically
  4. Status Tracking - Tracks maintenance state and history
  5. Default Subdomain Settings - New sites include all subdomains by default

Important: Sync operations preserve user-configured subdomain settings. Manual changes to include_subdomains, subdomain_list, and maintenance_url are never overwritten by sync operations.

Event Tracking

Maintenance Logs

from django_cfg.apps.maintenance.models import MaintenanceLog
 
# All operations are automatically logged
logs = MaintenanceLog.objects.filter(
    site__domain='example.com'
).order_by('-created_at')
 
for log in logs:
    print(f"{log.created_at}: {log.action}")
    print(f"  Status: {log.status}")
    print(f"  Duration: {log.duration_seconds}s")
    if log.error_message:
        print(f"  Error: {log.error_message}")

Log Statistics

# Get operation statistics
stats = MaintenanceLog.objects.get_stats(days=30)
print(f"Success rate: {stats['success_rate']:.1f}%")
print(f"Average duration: {stats['avg_duration']:.1f}s")
print(f"Total operations: {stats['total']}")

Configuration

API Key Management

from django_cfg.apps.maintenance.models import CloudflareApiKey
 
# Create API key
api_key = CloudflareApiKey.objects.create(
    name="Production Key",
    api_token="your_cloudflare_token_here",
    account_id="auto_discovered",  # Auto-filled on first use
    is_default=True,  # Use as default for new sites
    is_active=True
)
 
# Multiple API keys supported
api_key2 = CloudflareApiKey.objects.create(
    name="Development Key", 
    api_token="dev_token_here",
    is_active=True
)

Site Configuration

from django_cfg.apps.maintenance.models import CloudflareSite
 
# Manual site creation
site = CloudflareSite.objects.create(
    name="My Production Site",
    domain="example.com",
    api_key=api_key,
    
    # Optional: auto-discovered if not provided
    zone_id="zone_123",
    account_id="account_123",
    
    # Custom maintenance page
    maintenance_url="https://status.example.com",
    
    # Subdomain configuration (manual)
    include_subdomains=False,              # Don't use wildcard
    subdomain_list="api,dashboard,www",    # Specific subdomains
    
    # Site settings
    is_active=True
)
 
# User can modify subdomain settings later via admin or code:
site.include_subdomains = True    # Switch to include all subdomains
site.subdomain_list = ""          # Clear specific list
site.save()

🧪 Testing

Simple Tests

from django.test import TestCase
from django_cfg.apps.maintenance import CloudflareSite, MaintenanceService
 
class MaintenanceTest(TestCase):
    def setUp(self):
        self.api_key = CloudflareApiKey.objects.create(
            name="Test Key",
            api_token="test_token",
            is_default=True
        )
        self.site = CloudflareSite.objects.create(
            name="Test Site",
            domain="test.example.com",
            api_key=self.api_key
        )
    
    def test_maintenance_cycle(self):
        service = MaintenanceService(self.site)
        
        # Test enable
        log = service.enable_maintenance("Test reason")
        self.assertEqual(log.status, 'success')
        
        # Test status
        self.assertTrue(service.get_status())
        
        # Test disable
        log = service.disable_maintenance()
        self.assertEqual(log.status, 'success')
        self.assertFalse(service.get_status())

Test Coverage

Current test coverage includes:

  • ✅ Models - All model methods and managers
  • ✅ Services - Core maintenance operations
  • ✅ Utils - Retry logic and error handling
  • ✅ Commands - CLI command functionality

🔒 Security Features

Access Control

  • API Token Security - Tokens stored securely in database
  • Permission Validation - All operations validate API permissions
  • Error Handling - Safe error messages without sensitive data exposure

Input Validation

  • Domain Validation - Ensures valid domain formats
  • API Response Validation - Validates Cloudflare API responses
  • URL Validation - Validates custom maintenance URLs

Performance

Optimizations

  • Lazy Imports - Models and services loaded on demand
  • Retry Logic - Exponential backoff for API failures
  • JSON Serialization - Safe handling of datetime objects in logs
  • Efficient Queries - Custom managers with optimized querysets

Rate Limiting

# Built-in retry with exponential backoff
@retry_on_failure(max_retries=3, base_delay=1.0)
def _create_maintenance_page_rule(self):
    # Handles API rate limits automatically
    return self.client.page_rules.create(...)

Best Practices

1. Use Descriptive Reasons

# Good: Specific and informative
service.enable_maintenance("Database migration v2.1 - ETA 30 minutes")
 
# Avoid: Vague messages  
service.enable_maintenance("Maintenance")

2. Set Custom Maintenance URLs

# Branded maintenance page
site.maintenance_url = "https://status.yourcompany.com/?site=example.com"
site.save()

3. Configure Subdomains Appropriately

# For most sites: Include all subdomains (default)
site.include_subdomains = True
site.subdomain_list = ""
 
# For specific control: List only critical subdomains
site.include_subdomains = False
site.subdomain_list = "api,dashboard,www"  # Skip dev/test subdomains
 
# Mixed approach: Add specific subdomains to wildcard
# (not supported - use one approach or the other)

4. Monitor Logs

# Check for errors regularly
failed_logs = MaintenanceLog.objects.filter(
    status='failed',
    created_at__gte=timezone.now() - timedelta(days=1)
)
 
if failed_logs.exists():
    # Alert administrators
    send_alert_email(failed_logs)

5. Test in Development

# Always test maintenance flow
python manage.py maintenance enable dev.example.com --reason "Testing"
# Verify maintenance page loads
python manage.py maintenance disable dev.example.com

🆚 Migration from Complex Version

If migrating from the old complex maintenance app:

What’s Removed

  • ❌ Workers Support - Now uses Page Rules only
  • ❌ Monitoring System - External monitoring removed
  • ❌ Site Groups - Simplified to direct site management
  • ❌ User Ownership - Sites are global, not user-specific
  • ❌ Complex Templates - Uses simple URL redirects
  • ❌ API Endpoints - Admin and CLI only

What’s Simplified

  • ✅ 4 Models instead of 8+ models
  • ✅ Page Rules instead of Worker deployment
  • ✅ Simple CLI instead of complex filtering
  • ✅ Direct Operations instead of async processing
  • ✅ Cloudflare Free compatible

Migration Steps

  1. Export site data from old app
  2. Install new maintenance app
  3. Create API keys in admin
  4. Import/recreate sites
  5. Test maintenance operations

The simplified Maintenance app provides efficient site maintenance management with minimal complexity! 🌐

OverviewTasks