Environment Variables

Overview

FootyCollect uses environment variables for configuration. For local development, create a .env file in the project root or use the .envs/.local/ directory structure for Docker.

Copy deploy/env.example to .env as a starting point, then customize the values for your environment.

Django Core Settings

Core Django configuration options.

string

required

Django secret key for cryptographic signing. Generate a secure random string.Production: Use a strong random key (50+ characters)Development: Any string is fine

# Generate with Python
python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

boolean

default:"False"

Enable Django debug mode.Production: Must be FalseDevelopment: True

Never enable DEBUG in production! It exposes sensitive information.

string

required

Comma-separated list of allowed hostnames.Production: Your domain(s)

DJANGO_ALLOWED_HOSTS=footycollect.com,www.footycollect.com

Development: Local addresses

DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0

string

default:"admin/"

URL path for Django admin interface.For security, consider using a non-standard path in production:

DJANGO_ADMIN_URL=my-secret-admin-path/

Database

PostgreSQL database configuration.

string

required

PostgreSQL connection string in URL format.Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASEProduction:

DATABASE_URL=postgresql://footycollect:secure_password@localhost:5432/footycollect_db

Docker:

DATABASE_URL=postgresql://footycollect:local_password@postgres:5432/footycollect

integer

default:"60"

Database connection pooling lifetime in seconds.Recommended: 60 for production

Redis

Redis cache and Celery message broker configuration.

string

required

Redis connection string.Format: redis://HOST:PORT/DBProduction:

REDIS_URL=redis://localhost:6379/0

Docker:

REDIS_URL=redis://redis:6379/0

API Rate Limiting

Django REST Framework throttle configuration for /api/ endpoints.

string

default:"100/hour"

Rate limit for authenticated users.Format: requests/period (e.g., 100/hour, 1000/day)

DJANGO_DRF_USER_THROTTLE_RATE=100/hour

string

default:"20/hour"

Rate limit for anonymous users.

DJANGO_DRF_ANON_THROTTLE_RATE=20/hour

Security Headers

HTTPS and security header configuration for production.

boolean

default:"True"

Redirect all HTTP requests to HTTPS.Production: TrueDevelopment: False

boolean

default:"True"

Include subdomains in HSTS (HTTP Strict Transport Security) policy.Production: True

boolean

default:"True"

Enable HSTS preload.Production: True (submit to hstspreload.org)

boolean

default:"True"

Prevent MIME type sniffing.Production: True

SameSite cookie policy for session cookies.Options: Strict, Lax, NoneRecommended: Lax

SameSite cookie policy for CSRF cookies.Recommended: Lax

string

default:"strict-origin-when-cross-origin"

Referrer-Policy header value.Recommended: strict-origin-when-cross-origin

string

Permissions-Policy header for controlling browser features.Default disables geolocation, microphone, camera, and payment APIs:

DJANGO_PERMISSIONS_POLICY=geolocation=(), microphone=(), camera=(), payment=()

Content Security Policy (CSP)

Content-Security-Policy configuration to prevent XSS attacks.

boolean

default:"True"

Enable Content Security Policy.Production: TrueDevelopment: Can be False for easier debugging

string

Allowed sources for images. Use comma-separated values with quoted keywords.Default includes Gravatar and Football Kit Archive:

DJANGO_CSP_IMG_SRC='self', data:, blob:, https://www.gravatar.com, https://cdn.footballkitarchive.com, https://www.footballkitarchive.com, https://YOUR-BUCKET.s3.amazonaws.com

Update with your actual S3/R2 bucket domain if using cloud storage.

string

Default source policy (fallback for other directives).

DJANGO_CSP_DEFAULT_SRC='self'

string

Allowed sources for JavaScript.Default includes CDN for UI libraries:

DJANGO_CSP_SCRIPT_SRC='self', 'unsafe-inline', 'unsafe-eval', https://cdnjs.cloudflare.com

string

Allowed sources for CSS.

DJANGO_CSP_STYLE_SRC='self', 'unsafe-inline', https://cdnjs.cloudflare.com, https://fonts.googleapis.com

string

Allowed sources for fonts.

DJANGO_CSP_FONT_SRC='self', https://cdnjs.cloudflare.com, https://fonts.gstatic.com

string

Allowed sources for AJAX, WebSockets, and EventSource.

DJANGO_CSP_CONNECT_SRC='self'

string

Allowed sources that can embed this site in frames.

DJANGO_CSP_FRAME_ANCESTORS='self'

string

Allowed form submission targets.

DJANGO_CSP_FORM_ACTION='self'

Email Configuration

Email sending via SendGrid.

string

SendGrid API key for sending emails.Get from: https://app.sendgrid.com/settings/api_keys

SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxx

string

default:"https://api.sendgrid.com/v3/"

SendGrid API endpoint URL.

string

Default “from” address for emails.

DJANGO_DEFAULT_FROM_EMAIL=footycollect <noreply@your-domain.com>

string

“From” address for server error emails.

DJANGO_SERVER_EMAIL=footycollect <noreply@your-domain.com>

string

default:"[footycollect]"

Prefix added to email subjects.

Error Tracking (Sentry)

Sentry integration for error monitoring and performance tracking.

string

Sentry Data Source Name (DSN) for error reporting.Get from your Sentry project settings.

SENTRY_DSN=https://xxxxxxxxxxxxx@sentry.io/1234567

string

default:"production"

Environment name for Sentry (production, staging, development).

float

default:"0.0"

Percentage of transactions to sample for performance monitoring (0.0-1.0).0.0 = disabled, 1.0 = 100% of requestsRecommended: 0.1 (10%) for production to limit costs

Storage Backend

Media file storage configuration (AWS S3 or Cloudflare R2).

string

default:"local"

Storage backend for media files.Options:

local - Local filesystem (development)
aws - Amazon S3
r2 - Cloudflare R2

STORAGE_BACKEND=aws

AWS S3 Storage

Configuration when STORAGE_BACKEND=aws.

string

AWS IAM access key ID.

string

AWS IAM secret access key.

string

S3 bucket name for media files.

DJANGO_AWS_STORAGE_BUCKET_NAME=footycollect-media

string

default:"us-east-1"

AWS region for S3 bucket.

string

Custom domain for S3 bucket (optional, for CloudFront CDN).

DJANGO_AWS_S3_CUSTOM_DOMAIN=cdn.your-domain.com

Cloudflare R2 Storage

Configuration when STORAGE_BACKEND=r2.

string

Cloudflare R2 access key ID.

string

Cloudflare R2 secret access key.

string

R2 bucket name.

CLOUDFLARE_BUCKET_NAME=footycollect-media

string

R2 endpoint URL.Format: https://<account-id>.r2.cloudflarestorage.com

CLOUDFLARE_R2_ENDPOINT_URL=https://abc123.r2.cloudflarestorage.com

string

default:"auto"

R2 region (usually auto).

string

Custom domain for R2 bucket (optional).

CLOUDFLARE_R2_CUSTOM_DOMAIN=media.your-domain.com

External Image Downloads

Configuration for downloading images from external sources (e.g., Football Kit Archive).

string

Comma-separated list of allowed hostnames for external image downloads (SSRF protection).

DJANGO_ALLOWED_EXTERNAL_IMAGE_HOSTS=cdn.footballkitarchive.com,www.footballkitarchive.com

Only add trusted domains to prevent Server-Side Request Forgery (SSRF) attacks.

FKAPI Integration

Football Kit Archive API configuration.

string

IP address or hostname of the FKAPI server.Required for Football Kit Archive integration.

FKA_API_IP=192.168.1.100
# or
FKA_API_IP=fkapi.your-domain.com

See FKAPI GitHub for setup instructions.

string

API key for authenticating with FKAPI.

API_KEY=your-fkapi-authentication-key

Rotating Proxy

Optional proxy configuration for external image downloads to avoid rate limiting.

string

Proxy server URL.Supports HTTP, HTTPS, and SOCKS5 protocols:

ROTATING_PROXY_URL=http://proxy.example.com:8080
# or
ROTATING_PROXY_URL=socks5://proxy.example.com:1080

string

Proxy authentication username (if required).

string

Proxy authentication password (if required).

Compression

Static file compression configuration.

boolean

default:"True"

Enable django-compressor for CSS/JS minification.Production: TrueDevelopment: Can be False for faster builds

Example Configurations

Development (.env)

# Django Settings
DJANGO_SECRET_KEY=local-dev-key-not-for-production
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1

# Database
DATABASE_URL=postgresql://footycollect:devpassword@localhost:5432/footycollect_dev

# Redis
REDIS_URL=redis://localhost:6379/0

# Security (relaxed for local dev)
DJANGO_SECURE_SSL_REDIRECT=False
DJANGO_CSP_ENABLED=False

# Storage
STORAGE_BACKEND=local

# Compression
COMPRESS_ENABLED=False

Production (.env)

# Django Settings
DJANGO_SECRET_KEY=<generate-secure-50-char-key>
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=footycollect.com,www.footycollect.com
DJANGO_ADMIN_URL=secret-admin-path/

# Database
DATABASE_URL=postgresql://footycollect:secure_db_pass@localhost:5432/footycollect_prod
CONN_MAX_AGE=60

# Redis
REDIS_URL=redis://localhost:6379/0

# API Rate Limiting
DJANGO_DRF_USER_THROTTLE_RATE=100/hour
DJANGO_DRF_ANON_THROTTLE_RATE=20/hour

# Security
DJANGO_SECURE_SSL_REDIRECT=True
DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS=True
DJANGO_SECURE_HSTS_PRELOAD=True
DJANGO_SECURE_CONTENT_TYPE_NOSNIFF=True
DJANGO_SESSION_COOKIE_SAMESITE=Lax
DJANGO_CSRF_COOKIE_SAMESITE=Lax

# CSP
DJANGO_CSP_ENABLED=True
DJANGO_CSP_IMG_SRC='self', data:, blob:, https://www.gravatar.com, https://cdn.footballkitarchive.com, https://footycollect-media.s3.amazonaws.com

# Email (SendGrid)
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxx
DJANGO_DEFAULT_FROM_EMAIL=FootyCollect <noreply@footycollect.com>
DJANGO_SERVER_EMAIL=FootyCollect <noreply@footycollect.com>

# Sentry
SENTRY_DSN=https://xxxxxxx@sentry.io/1234567
SENTRY_ENVIRONMENT=production
SENTRY_TRACES_SAMPLE_RATE=0.1

# Storage (AWS S3)
STORAGE_BACKEND=aws
DJANGO_AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXXXXX
DJANGO_AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DJANGO_AWS_STORAGE_BUCKET_NAME=footycollect-media
DJANGO_AWS_S3_REGION_NAME=us-east-1

# External Images
DJANGO_ALLOWED_EXTERNAL_IMAGE_HOSTS=cdn.footballkitarchive.com,www.footballkitarchive.com

# FKAPI
FKA_API_IP=192.168.1.100
API_KEY=your-fkapi-key

# Compression
COMPRESS_ENABLED=True

Docker Development (.envs/.local/)

.envs/.local/.django:

DJANGO_SETTINGS_MODULE=config.settings.local
DJANGO_SECRET_KEY=docker-local-secret-key
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0

REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0

EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=mailpit
EMAIL_PORT=1025

.envs/.local/.postgres:

POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=footycollect
POSTGRES_USER=footycollect
POSTGRES_PASSWORD=local_dev_password

DATABASE_URL=postgresql://footycollect:local_dev_password@postgres:5432/footycollect

Validation

Run Django’s production deployment checks:

python manage.py check --deploy

This validates:

Security settings
Required environment variables
Database connectivity
Static file configuration

Next Steps

Local Setup

Manual local installation guide

Docker Setup

Docker Compose development environment

Deployment

Production deployment guide

Development

Learn about the architecture

Get Started

Installation

Core Features

User Guide

Architecture

Development

Deployment

Overview

Django Core Settings

Database

Redis

API Rate Limiting

Security Headers

Content Security Policy (CSP)

Email Configuration

Error Tracking (Sentry)

Storage Backend

AWS S3 Storage

Cloudflare R2 Storage

External Image Downloads

FKAPI Integration

Rotating Proxy

Compression

Example Configurations

Development (.env)

Production (.env)

Docker Development (.envs/.local/)

Validation

Next Steps

Local Setup

Docker Setup

Deployment

Development

​Overview

​Django Core Settings

​Database

​Redis

​API Rate Limiting

​Security Headers

​Content Security Policy (CSP)

​Email Configuration

​Error Tracking (Sentry)

​Storage Backend

​AWS S3 Storage

​Cloudflare R2 Storage

​External Image Downloads

​FKAPI Integration

​Rotating Proxy

​Compression

​Example Configurations

​Development (.env)

​Production (.env)

​Docker Development (.envs/.local/)

​Validation

​Next Steps

Local Setup

Docker Setup

Deployment

Development

Overview

Django Core Settings

Database

Redis

API Rate Limiting

Security Headers

Content Security Policy (CSP)

Email Configuration

Error Tracking (Sentry)

Storage Backend

AWS S3 Storage

Cloudflare R2 Storage

External Image Downloads

FKAPI Integration

Rotating Proxy

Compression

Example Configurations

Development (.env)

Production (.env)

Docker Development (.envs/.local/)

Validation

Next Steps