Configuration

django-cloudflareimages-toolkit provides flexible configuration options for different deployment scenarios and image management needs.

Required Settings

The following settings must be configured in your Django settings file:

CLOUDFLARE_IMAGES = {
    'ACCOUNT_ID': 'your-cloudflare-account-id',
    'API_TOKEN': 'your-api-token',
    'ACCOUNT_HASH': 'your-account-hash',
}

Account Information

ACCOUNT_ID: Your Cloudflare account ID (found in the right sidebar of any Cloudflare dashboard page)
API_TOKEN: API token with Cloudflare Images permissions
ACCOUNT_HASH: Your account hash for image URLs (found in Images dashboard)

Optional Settings

You can customize additional behavior with these optional settings:

CLOUDFLARE_IMAGES = {
    # Required settings
    'ACCOUNT_ID': 'your-account-id',
    'API_TOKEN': 'your-api-token',
    'ACCOUNT_HASH': 'your-account-hash',

    # Optional settings
    'DEFAULT_VARIANT': 'public',           # Default image variant for URLs
    'UPLOAD_TIMEOUT': 300,                 # Upload timeout in seconds
    'WEBHOOK_SECRET': 'your-webhook-secret', # For webhook verification
    'CLEANUP_EXPIRED_HOURS': 24,           # Hours before cleaning up expired uploads
    'MAX_FILE_SIZE': 10 * 1024 * 1024,     # Maximum file size (10MB default)
    'ALLOWED_FORMATS': ['jpeg', 'png', 'gif', 'webp'],  # Allowed image formats
    'REQUIRE_SIGNED_URLS': False,          # Whether to require signed URLs
    'DEFAULT_METADATA': {},                # Default metadata for uploads
}

Environment Variables

For security, store sensitive configuration in environment variables:

# .env file
CLOUDFLARE_ACCOUNT_ID=your_account_id_here
CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ACCOUNT_HASH=your_account_hash_here
CLOUDFLARE_WEBHOOK_SECRET=your_webhook_secret_here

Then reference them in your Django settings:

import os

CLOUDFLARE_IMAGES = {
    'ACCOUNT_ID': os.getenv('CLOUDFLARE_ACCOUNT_ID'),
    'API_TOKEN': os.getenv('CLOUDFLARE_API_TOKEN'),
    'ACCOUNT_HASH': os.getenv('CLOUDFLARE_ACCOUNT_HASH'),
    'WEBHOOK_SECRET': os.getenv('CLOUDFLARE_WEBHOOK_SECRET'),
}

CloudflareImage Model Configuration

The package uses a Django model to track image uploads and metadata:

Model Fields

class CloudflareImage(models.Model):
    cloudflare_id = models.CharField(max_length=255, unique=True)
    filename = models.CharField(max_length=255)
    uploaded_at = models.DateTimeField(auto_now_add=True)
    file_size = models.PositiveIntegerField(null=True, blank=True)
    width = models.PositiveIntegerField(null=True, blank=True)
    height = models.PositiveIntegerField(null=True, blank=True)
    format = models.CharField(max_length=10, blank=True)
    variants = models.JSONField(default=dict, blank=True)
    metadata = models.JSONField(default=dict, blank=True)
    is_ready = models.BooleanField(default=False)
    upload_url = models.URLField(blank=True)
    upload_expires_at = models.DateTimeField(null=True, blank=True)

Django Admin Integration

The package includes Django admin integration for image management:

# The admin interface provides:
# 1. View all uploaded images with thumbnails
# 2. Search and filter images by various criteria
# 3. View image metadata and variants
# 4. Delete images (removes from both Django and Cloudflare)
# 5. Generate new upload URLs

Custom Admin Configuration

You can customize the admin interface:

# admin.py
from django.contrib import admin
from django_cloudflareimages_toolkit.admin import CloudflareImageAdmin
from django_cloudflareimages_toolkit.models import CloudflareImage

# Unregister the default admin
admin.site.unregister(CloudflareImage)

# Register with custom configuration
@admin.register(CloudflareImage)
class CustomCloudflareImageAdmin(CloudflareImageAdmin):
    list_display = ['filename', 'uploaded_at', 'file_size', 'is_ready']
    list_filter = ['is_ready', 'format', 'uploaded_at']
    search_fields = ['filename', 'cloudflare_id']

Image Variants Configuration

Cloudflare Images supports variants for different image sizes and formats:

Creating Variants

Create variants in your Cloudflare Images dashboard or via API:

from django_cloudflareimages_toolkit.services import CloudflareImagesService

service = CloudflareImagesService()

# Create a thumbnail variant
service.create_variant(
    variant_id='thumbnail',
    options={
        'fit': 'scale-down',
        'width': 200,
        'height': 200,
    }
)

Using Variants in Templates

<!-- In your Django templates -->
<img src="{{ image.get_url }}" alt="Original image">
<img src="{{ image.get_url:'thumbnail' }}" alt="Thumbnail">
<img src="{{ image.get_url:'avatar' }}" alt="Avatar">

Webhook Configuration

Configure webhooks to receive real-time upload notifications:

URL Configuration

Add the webhook URLs to your Django project:

# urls.py
from django.urls import path, include

urlpatterns = [
    # ... other patterns
    path('cloudflare-images/', include('django_cloudflareimages_toolkit.urls')),
]

Cloudflare Dashboard Setup

Go to your Cloudflare Images dashboard
Navigate to the Webhooks section
Add a new webhook with URL: https://yourdomain.com/cloudflare-images/webhook/
Set the webhook secret in your Django settings

Webhook Security

The package verifies webhook signatures for security:

CLOUDFLARE_IMAGES = {
    # ... other settings
    'WEBHOOK_SECRET': 'your-webhook-secret-from-cloudflare',
}

Field Configuration

Configure the CloudflareImageField for your models:

Basic Usage

from django.db import models
from django_cloudflareimages_toolkit.fields import CloudflareImageField

class Profile(models.Model):
    name = models.CharField(max_length=100)
    avatar = CloudflareImageField()

Advanced Configuration

class Product(models.Model):
    name = models.CharField(max_length=100)
    image = CloudflareImageField(
        variants=['thumbnail', 'large'],  # Specific variants to create
        metadata={'category': 'product'},  # Default metadata
        required_signed_urls=True,         # Require signed URLs
    )

Security Configuration

API Token Permissions

Ensure your API token has the minimum required permissions:

Cloudflare Images:Edit - For uploading and managing images
Zone:Zone Settings:Read - For account information (if needed)

Token Security

# Use different tokens for different environments
# Production settings
CLOUDFLARE_IMAGES = {
    'API_TOKEN': os.getenv('CLOUDFLARE_PROD_API_TOKEN'),
    # ... other settings
}

# Development settings
CLOUDFLARE_IMAGES = {
    'API_TOKEN': os.getenv('CLOUDFLARE_DEV_API_TOKEN'),
    # ... other settings
}

Upload Security

Configure upload restrictions:

CLOUDFLARE_IMAGES = {
    # ... other settings
    'MAX_FILE_SIZE': 5 * 1024 * 1024,  # 5MB limit
    'ALLOWED_FORMATS': ['jpeg', 'png'],  # Only JPEG and PNG
    'REQUIRE_SIGNED_URLS': True,        # Require signed URLs for access
}

Logging Configuration

Configure logging to monitor image operations:

# settings.py
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{levelname} {asctime} {module} {process:d} {thread:d} {message}',
            'style': '{',
        },
    },
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': 'cloudflare_images.log',
            'formatter': 'verbose',
        },
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
        },
    },
    'loggers': {
        'django_cloudflareimages_toolkit': {
            'handlers': ['file', 'console'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

Testing Configuration

For testing environments:

# settings/test.py
if 'test' in sys.argv:
    # Use test credentials or mock the service
    CLOUDFLARE_IMAGES = {
        'ACCOUNT_ID': 'test-account-id',
        'API_TOKEN': 'test-api-token',
        'ACCOUNT_HASH': 'test-account-hash',
    }

    # Or mock the service entirely
    CLOUDFLARE_IMAGES_MOCK = True

Performance Configuration

Optimize performance with these settings:

CLOUDFLARE_IMAGES = {
    # ... other settings
    'UPLOAD_TIMEOUT': 60,           # Shorter timeout for faster failures
    'CLEANUP_EXPIRED_HOURS': 1,     # More frequent cleanup
    'DEFAULT_VARIANT': 'optimized', # Use optimized variant by default
}

Best Practices

Environment Separation: Use different API tokens for dev/staging/production
Secure Storage: Never commit API tokens to version control
Monitor Usage: Set up logging to track image operations
Regular Cleanup: Use the cleanup management command regularly
Variant Strategy: Plan your image variants based on actual usage
Webhook Security: Always verify webhook signatures
Error Handling: Implement proper error handling for upload failures
Testing: Test image uploads in all environments before deployment