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.

DJANGO_SECRET_KEY

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())"

DJANGO_DEBUG

boolean

default:"False"

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

Never enable DEBUG in production! It exposes sensitive information.

DJANGO_ALLOWED_HOSTS

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

DJANGO_ADMIN_URL

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.

DATABASE_URL

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

CONN_MAX_AGE

integer

default:"60"

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

Redis

Redis cache and Celery message broker configuration.

REDIS_URL

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.

DJANGO_DRF_USER_THROTTLE_RATE

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

DJANGO_DRF_ANON_THROTTLE_RATE

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.

DJANGO_SECURE_SSL_REDIRECT

boolean

default:"True"

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

DJANGO_SECURE_HSTS_INCLUDE_SUBDOMAINS

boolean

default:"True"

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

DJANGO_SECURE_HSTS_PRELOAD

boolean

default:"True"

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

DJANGO_SECURE_CONTENT_TYPE_NOSNIFF

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

DJANGO_REFERRER_POLICY

string

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

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

DJANGO_PERMISSIONS_POLICY

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.

DJANGO_CSP_ENABLED

boolean

default:"True"

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

DJANGO_CSP_IMG_SRC

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.

DJANGO_CSP_DEFAULT_SRC

string

Default source policy (fallback for other directives).

DJANGO_CSP_DEFAULT_SRC='self'

DJANGO_CSP_SCRIPT_SRC

string

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

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

DJANGO_CSP_STYLE_SRC

string

Allowed sources for CSS.

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

DJANGO_CSP_FONT_SRC

string

Allowed sources for fonts.

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

DJANGO_CSP_CONNECT_SRC

string

Allowed sources for AJAX, WebSockets, and EventSource.

DJANGO_CSP_CONNECT_SRC='self'

DJANGO_CSP_FRAME_ANCESTORS

string

Allowed sources that can embed this site in frames.

DJANGO_CSP_FRAME_ANCESTORS='self'

DJANGO_CSP_FORM_ACTION

string

Allowed form submission targets.

DJANGO_CSP_FORM_ACTION='self'

Email Configuration

Email sending via SendGrid.

SENDGRID_API_KEY

string

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

SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxx

SENDGRID_API_URL

string

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

SendGrid API endpoint URL.

DJANGO_DEFAULT_FROM_EMAIL

string

Default “from” address for emails.

DJANGO_DEFAULT_FROM_EMAIL=footycollect <[email protected]>

DJANGO_SERVER_EMAIL

string

“From” address for server error emails.

DJANGO_SERVER_EMAIL=footycollect <[email protected]>

DJANGO_EMAIL_SUBJECT_PREFIX

string

default:"[footycollect]"

Prefix added to email subjects.

Error Tracking (Sentry)

Sentry integration for error monitoring and performance tracking.

SENTRY_DSN

string

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

SENTRY_DSN=https://[email protected]/1234567

SENTRY_ENVIRONMENT

string

default:"production"

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

SENTRY_TRACES_SAMPLE_RATE

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).

STORAGE_BACKEND

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.

DJANGO_AWS_ACCESS_KEY_ID

string

AWS IAM access key ID.

DJANGO_AWS_SECRET_ACCESS_KEY

string

AWS IAM secret access key.

DJANGO_AWS_STORAGE_BUCKET_NAME

string

S3 bucket name for media files.

DJANGO_AWS_STORAGE_BUCKET_NAME=footycollect-media

DJANGO_AWS_S3_REGION_NAME

string

default:"us-east-1"

AWS region for S3 bucket.

DJANGO_AWS_S3_CUSTOM_DOMAIN

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.

CLOUDFLARE_ACCESS_KEY_ID

string

Cloudflare R2 access key ID.

CLOUDFLARE_SECRET_ACCESS_KEY

string

Cloudflare R2 secret access key.

CLOUDFLARE_BUCKET_NAME

string

R2 bucket name.

CLOUDFLARE_BUCKET_NAME=footycollect-media

CLOUDFLARE_R2_ENDPOINT_URL

string

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

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

CLOUDFLARE_R2_REGION

string

default:"auto"

R2 region (usually auto).

CLOUDFLARE_R2_CUSTOM_DOMAIN

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).

DJANGO_ALLOWED_EXTERNAL_IMAGE_HOSTS

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.

FKA_API_IP

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.

API_KEY

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.

ROTATING_PROXY_URL

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

ROTATING_PROXY_USERNAME

string

Proxy authentication username (if required).

ROTATING_PROXY_PASSWORD

string

Proxy authentication password (if required).

Compression

Static file compression configuration.

COMPRESS_ENABLED

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 <[email protected]>
DJANGO_SERVER_EMAIL=FootyCollect <[email protected]m>

# Sentry
SENTRY_DSN=https://[email protected]/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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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