Environment Variables Reference

This page provides a complete reference for all environment variables used in Pixelflare.

Summary

95 total variables · 9 required · 86 optional · 14 sensitive · 1 deprecated

Auto-generated Documentation

This documentation is automatically generated from the environment schema. See scripts/lib/env-schema.cjs for the source.

Quick Reference

Minimum required environment variables:

bash

# Cloudflare API token for Terraform provider authentication and custom hostname management
CLOUDFLARE_API_TOKEN="your_api_token_here"

# Cloudflare account ID for resource creation
CLOUDFLARE_ACCOUNT_ID="your_account_id_here"

# Root domain for all services (used for Auth
DOMAIN="pixelflare.cc"

# Public hostname for CDN URLs (generated by Terraform)
CDN_PUBLIC_HOST="pixelflare.cc"

# API hostname (generated by Terraform)
API_HOST="pixelflare.cc/api"

# Frontend application hostname (generated by Terraform)
APP_HOST="app.pixelflare.cc"

# R2 bucket binding for image storage
R2_BUCKET="your-value-here"

# D1 database binding
DB="your-value-here"

# KV namespace binding for caching
KV_CACHE="your-value-here"

Jump to any environment variable:

Usage Guide

Where Variables Are Used

Terraform: Variables passed to Terraform during infrastructure deployment
Worker Secret: Sensitive values stored as Cloudflare Worker secrets
Wrangler Config: Variables in wrangler configuration (auto-generated)
Worker Binding: Cloudflare resource bindings (R2, D1, KV, Queues, etc.)
Frontend: Variables used in SvelteKit frontend build

Setting Variables

Create a .env file in the project root:

bash

# Copy example file
cp .env.example .env

# Edit with your values
nano .env

For Terraform deployment, you can also use:

bash

# Copy Terraform example
cp terraform/terraform.tfvars.example terraform/terraform.tfvars

# Edit with your values
nano terraform/terraform.tfvars

Authentication & Security

2 required, 18 optional (20 total)

`CLOUDFLARE_API_TOKEN`

IMPORTANT

This variable is required. The application will not function without it. [!WARNING] Sensitive Value Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Cloudflare API token for Terraform provider authentication and custom hostname management

Type: string
Required: required sensitive
Used in: Terraform Worker Secret
Example: your_api_token_here
Validation: Must have Account, Zone, SSL and Certificates permissions for custom domains
Terraform: cloudflare_api_token, cloudflare_api_token_for_custom_domains

TIP

Also passed to Worker as secret for custom domain management

`CLOUDFLARE_ACCOUNT_ID`

IMPORTANT

This variable is required. The application will not function without it.

Cloudflare account ID for resource creation

Type: string
Required: required
Used in: Terraform Worker Secret
Example: your_account_id_here
Validation: 32-character hex string
Terraform: cloudflare_account_id

TIP

Also needed as Worker secret for analytics batch aggregation

Critical Issue

Must be set as Worker secret for analytics/cache purging

`CLOUDFLARE_ZONE_ID`

Cloudflare zone ID for cache purging and custom hostname management

Type: string
Required: optional
Used in: Terraform Worker Secret Wrangler Config
Example: zone_id_here
Terraform: cloudflare_zone_id_for_custom_domains
Wrangler: CLOUDFLARE_ZONE_ID

TIP

Required for cache purging and custom domain feature. Terraform passes this to Worker as environment variable.

`GITHUB_OAUTH_CLIENT_ID`

GitHub OAuth application client ID for Cloudflare Access and Better Auth

Type: string (default: "")
Required: optional
Default: ""
Used in: Terraform Wrangler Config
Example: Iv1.a1b2c3d4e5f6g7h8
Terraform: github_oauth_client_id
Wrangler: GITHUB_OAUTH_CLIENT_ID

TIP

Used for both Cloudflare Access and Better Auth. Create at https://github.com/settings/developers

`GITHUB_OAUTH_CLIENT_SECRET`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

GitHub OAuth application client secret

Type: string (default: "")
Required: optional sensitive
Default: ""
Used in: Terraform Worker Secret
Example: your_github_oauth_secret_here
Terraform: github_oauth_client_secret

TIP

Used for both Cloudflare Access and Better Auth

`GOOGLE_OAUTH_CLIENT_ID`

Google OAuth client ID for Better Auth

Type: string (default: "")
Required: optional
Default: ""
Used in: Terraform Wrangler Config
Example: 123456789-abcdefg.apps.googleusercontent.com
Terraform: google_oauth_client_id
Wrangler: GOOGLE_OAUTH_CLIENT_ID

TIP

For Better Auth Google OAuth. Create at https://console.cloud.google.com/apis/credentials

`GOOGLE_OAUTH_CLIENT_SECRET`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Google OAuth client secret for Better Auth

Type: string (default: "")
Required: optional sensitive
Default: ""
Used in: Terraform Worker Secret
Example: GOCSPX-...
Terraform: google_oauth_client_secret

TIP

For Better Auth Google OAuth

`MICROSOFT_OAUTH_CLIENT_ID`

Microsoft Entra ID (Azure AD) OAuth client ID for Auth.js

Type: string (default: "")
Required: optional
Default: ""
Used in: Terraform Wrangler Config
Example: 12345678-1234-1234-1234-123456789012
Terraform: microsoft_oauth_client_id
Wrangler: MICROSOFT_OAUTH_CLIENT_ID

TIP

For Auth.js Microsoft OAuth. Create at https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps

`MICROSOFT_OAUTH_CLIENT_SECRET`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Microsoft Entra ID (Azure AD) OAuth client secret

Type: string (default: "")
Required: optional sensitive
Default: ""
Used in: Terraform Worker Secret
Example: your_microsoft_oauth_secret_here
Terraform: microsoft_oauth_client_secret

TIP

For Auth.js Microsoft OAuth

`ALLOWED_EMAILS`

Comma-separated list of allowed email addresses for Access

Type: string[] (default: [])
Required: optional
Default: []
Used in: Terraform
Example: alice@example.com,bob@example.com
Terraform: allowed_emails

`ALLOWED_EMAIL_DOMAINS`

Comma-separated list of allowed email domains for Access

Type: string[] (default: [])
Required: optional
Default: []
Used in: Terraform
Example: example.com,company.com
Terraform: allowed_email_domains

`ACCESS_TEAM_DOMAIN`

Cloudflare Access team domain (if using existing team)

Type: string (default: "")
Required: optional
Default: ""
Used in: Terraform
Example: myteam
Terraform: access_team_domain

TIP

Leave empty to create new team

`AUTH_MODE`

Authentication mode: none, cloudflare, or authjs

Type: string (default: "cloudflare")
Required: optional
Default: "cloudflare"
Used in: Terraform Wrangler Config Frontend
Example: cloudflare
Validation: none | cloudflare | authjs
Terraform: auth_mode
Wrangler: AUTH_MODE

TIP

Defaults to cloudflare for backward compatibility. Set to authjs to use Auth.js with GitHub/Google OAuth

`AUTH_SECRET`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Secret key for Auth.js (required when AUTH_MODE=authjs)

Type: string
Required: optional sensitive
Used in: Terraform Worker Secret
Example: your-super-secret-random-string-here-min-32-chars
Validation: Long random string (minimum 32 characters)
Terraform: auth_secret

TIP

Only required when using Auth.js mode. Generate with: openssl rand -base64 32

`CF_ACCESS_AUD`

Cloudflare Access audience tag (generated by Terraform)

Type: string
Required: optional
Used in: Wrangler Config
Wrangler: CF_ACCESS_AUD

TIP

Set to "dev" for no-auth development mode

`CF_ACCESS_CERTS_URL`

Cloudflare Access certificates URL (generated by Terraform)

Type: string
Required: optional
Used in: Wrangler Config
Example: https://as93.cloudflareaccess.com/cdn-cgi/access/certs
Wrangler: CF_ACCESS_CERTS_URL

`API_HASH_SECRET`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager. [!NOTE] Auto-generated Terraform generates this automatically if not provided. You typically do not need to set this manually.

Secret for hashing API keys (auto-generated if empty)

Type: string (default: "")
Required: optional sensitive
Used in: Terraform Worker Secret
Validation: 64-character random string
Terraform: api_hash_secret

TIP

Terraform generates if not provided

`UPLOAD_TOKEN_SECRET`

Sensitive Value

Secret for HMAC signing of upload URLs (auto-generated)

Type: string
Required: optional sensitive
Used in: Worker Secret
Validation: 64-character random string

TIP

Always auto-generated by Terraform

`BACKUP_ENCRYPTION_KEY`

Sensitive Value

AES-256 encryption key for S3 backup credentials (auto-generated)

Type: string
Required: optional sensitive
Used in: Worker Secret
Validation: 64-character random string

TIP

Always auto-generated by Terraform

`ENCRYPTION_ROOT_KEY`

Sensitive Value

Root encryption key for wrapping TMKs (auto-generated)

Type: string
Required: optional sensitive
Used in: Worker Secret
Validation: Minimum 32-character random string

TIP

Required for encryption feature. Auto-generated by Terraform if not provided. If lost, encrypted images cannot be decrypted.

Infrastructure

4 required, 7 optional (11 total)

`DOMAIN`

IMPORTANT

This variable is required. The application will not function without it.

Root domain for all services (used for Auth.js cookie domain)

Type: string
Required: required
Used in: Terraform api
Example: pixelflare.cc
Validation: Must be a valid domain name
Terraform: domain

`FRONTEND_HOST`

Frontend Pages deployment URL (used for CORS during SSR)

Type: string
Required: optional
Used in: Wrangler Config Worker Secret api
Example: pixflare-production-frontend.pages.dev
Validation: Must be a valid Cloudflare Pages deployment URL

TIP

Used by API for CORS (SSR requests) and for custom domain profile HTML fetching. If not set, SSR will not work.

`PROJECT_NAME`

Project name used for resource naming

Type: string (default: "pixflare")
Required: optional
Default: "pixflare"
Used in: Terraform
Example: pixflare
Terraform: project_name

`ENVIRONMENT`

Environment identifier (production, staging, dev)

Type: string (default: "production")
Required: optional
Default: "production"
Used in: Terraform Wrangler Config
Example: production
Validation: production | staging | development
Terraform: environment
Wrangler: ENVIRONMENT

`SUBDOMAIN_APP`

Subdomain for frontend application

Type: string (default: "app")
Required: optional
Default: "app"
Used in: Terraform
Example: app
Terraform: subdomains.app

`SUBDOMAIN_API`

Subdomain for API

Type: string (default: "api")
Required: optional
Default: "api"
Used in: Terraform
Example: api
Terraform: subdomains.api

`SUBDOMAIN_CDN`

Subdomain for CDN

Type: string (default: "cdn")
Required: optional
Default: "cdn"
Used in: Terraform
Example: cdn
Terraform: subdomains.cdn

`CDN_PUBLIC_HOST`

IMPORTANT

This variable is required. The application will not function without it.

Public hostname for CDN URLs (generated by Terraform)

Type: string
Required: required
Used in: Wrangler Config
Example: pixelflare.cc
Wrangler: CDN_PUBLIC_HOST

TIP

Generated from domain + subdomain or gateway config

`API_HOST`

IMPORTANT

This variable is required. The application will not function without it.

API hostname (generated by Terraform)

Type: string
Required: required
Used in: Wrangler Config
Example: pixelflare.cc/api
Wrangler: API_HOST

TIP

Includes /api path when gateway is enabled

`APP_HOST`

IMPORTANT

This variable is required. The application will not function without it.

Frontend application hostname (generated by Terraform)

Type: string
Required: required
Used in: Wrangler Config
Example: app.pixelflare.cc
Wrangler: APP_HOST

`CUSTOM_DOMAIN_FALLBACK_CNAME`

CNAME target for custom domain verification (generated by Terraform)

Type: string
Required: optional
Used in: Wrangler Config
Example: cdn.pixelflare.cc
Wrangler: CUSTOM_DOMAIN_FALLBACK_CNAME

TIP

Users point their custom domain CNAME to this value

Storage & Resources

3 required, 11 optional (14 total)

`R2_BUCKET`

IMPORTANT

This variable is required. The application will not function without it.

R2 bucket binding for image storage

Type: string
Required: required
Used in: Worker Binding

TIP

Cloudflare R2 bucket binding (configured by Terraform)

`R2_BUCKET_NAME`

R2 bucket name for display in status endpoint

Type: string
Required: optional
Used in: Wrangler Config
Wrangler: R2_BUCKET_NAME

TIP

Generated by wrangler config script

`R2_CUSTOM_DOMAIN`

Custom domain for R2 bucket (for image resizing)

Type: string
Required: optional
Used in: Terraform Wrangler Config
Example: r2.pixelflare.cc
Terraform: r2_custom_domain
Wrangler: R2_CUSTOM_DOMAIN

`DB`

IMPORTANT

This variable is required. The application will not function without it.

D1 database binding

Type: string
Required: required
Used in: Worker Binding

TIP

Cloudflare D1 database binding (configured by Terraform)

`D1_DB_NAME`

D1 database name for display in status endpoint

Type: string
Required: optional
Used in: Wrangler Config
Wrangler: D1_DB_NAME

TIP

Generated by wrangler config script

`KV_CACHE`

IMPORTANT

This variable is required. The application will not function without it.

KV namespace binding for caching

Type: string
Required: required
Used in: Worker Binding

TIP

Cloudflare KV namespace binding (configured by Terraform)

`KV_CACHE_ID`

KV namespace ID for display in status endpoint

Type: string
Required: optional
Used in: Wrangler Config
Wrangler: KV_CACHE_ID

TIP

Generated by wrangler config script

`VARIANT_QUEUE`

Queue binding for image variant processing

Type: string
Required: optional
Used in: Worker Binding

TIP

Cloudflare Queue binding (configured by Terraform if ENABLE_QUEUES=true)

`QUEUE_VARIANT_NAME`

Variant queue name for display in status endpoint

Type: string
Required: optional
Used in: Wrangler Config
Wrangler: QUEUE_VARIANT_NAME

TIP

Generated by wrangler config script

`BACKUP_QUEUE`

Queue binding for backup sync

Type: string
Required: optional
Used in: Worker Binding

TIP

Cloudflare Queue binding (configured by Terraform if ENABLE_QUEUES=true)

`CUSTOM_DOMAIN_QUEUE`

Queue binding for custom domain verification polling

Type: string
Required: optional
Used in: Worker Binding

TIP

Cloudflare Queue binding (configured by Terraform if ENABLE_CUSTOM_DOMAINS=true)

`ANALYTICS`

Analytics Engine dataset binding

Type: string
Required: optional
Used in: Worker Binding

TIP

Cloudflare Analytics Engine binding (configured by Terraform if ENABLE_ANALYTICS=true)

`AI`

Workers AI binding

Type: string
Required: optional
Used in: Worker Binding

TIP

Cloudflare AI binding (configured by Terraform if ENABLE_AI_*=true)

`VECTORIZE`

Vectorize index binding for semantic search

Type: string
Required: optional
Used in: Worker Binding

TIP

Cloudflare Vectorize binding (configured by Terraform if ENABLE_VECTORIZE=true)

Feature Flags

`ENABLE_ACCESS`

Deprecated

This variable is deprecated since 2024. Use AUTH_MODE instead. Use AUTH_MODE=cloudflare instead for better authentication flexibility

Enable Cloudflare Access authentication

Type: boolean (default: true)
Required: optional deprecated
Default: true
Used in: Terraform
Terraform: enable_access

TIP

This is kept for backward compatibility.

`ENABLE_QUEUES`

Enable Cloudflare Queues for async processing

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform
Terraform: enable_queues

`ENABLE_WORKER_ROUTES`

Configure custom domain routes for Workers (api.domain.com, cdn.domain.com)

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform
Terraform: enable_worker_routes

`ENABLE_ANALYTICS`

Enable Analytics Engine

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform
Terraform: enable_analytics

`ENABLE_VECTORIZE`

Enable Vectorize for semantic image search

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform
Terraform: enable_vectorize

`ENABLE_AI_CLASSIFICATION`

Enable AI image classification

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform Wrangler Config
Terraform: enable_ai_classification
Wrangler: ENABLE_AI_CLASSIFICATION

`ENABLE_AI_NSFW_DETECTION`

Enable AI NSFW detection

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform Wrangler Config
Terraform: enable_ai_nsfw_detection
Wrangler: ENABLE_AI_NSFW_DETECTION

`AUDIT_LOG_ENABLED`

Enable audit logging for all mutations

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform Wrangler Config
Terraform: audit_log_enabled
Wrangler: AUDIT_LOG_ENABLED

`USAGE_LIMITS_ENABLED`

Enable usage limits and quotas

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform Wrangler Config
Terraform: usage_limits_enabled
Wrangler: USAGE_LIMITS_ENABLED

`STRIPE_ENABLED`

Enable Stripe billing and subscriptions

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform Wrangler Config
Terraform: stripe_enabled
Wrangler: STRIPE_ENABLED

TIP

When disabled, all users have unlimited usage. Enable for paid instances.

`GITHUB_SPONSORS_CHECK_ENABLED`

Enable GitHub Sponsors integration for automatic pro plan upgrades

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform Wrangler Config
Terraform: github_sponsors_check_enabled
Wrangler: GITHUB_SPONSORS_CHECK_ENABLED

TIP

When enabled, users who sponsor the project on GitHub automatically get pro plan access.

`STRIPE_SECRET_KEY`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Stripe secret API key for backend subscription management

Type: string
Required: optional sensitive
Used in: Terraform
Example: sk_test_... or sk_live_...
Terraform: stripe_secret_key

TIP

Get from Stripe Dashboard > Developers > API keys. Use test keys for development.

`STRIPE_PUBLISHABLE_KEY`

Stripe publishable key for frontend

Type: string
Required: optional
Used in: Terraform Wrangler Config
Example: pk_test_... or pk_live_...
Terraform: stripe_publishable_key
Wrangler: STRIPE_PUBLISHABLE_KEY

TIP

Safe to expose publicly. Get from Stripe Dashboard > Developers > API keys.

`STRIPE_WEBHOOK_SECRET`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Stripe webhook signing secret for verifying webhook events

Type: string
Required: optional sensitive
Used in: Terraform
Example: whsec_...
Terraform: stripe_webhook_secret

TIP

Get from Stripe Dashboard > Developers > Webhooks after creating webhook endpoint. Endpoint URL: https://your-domain.com/v1/billing/webhook

`ENABLE_CUSTOM_DOMAINS`

Enable custom domain support (Cloudflare for SaaS)

Type: boolean (default: false)
Required: optional
Default: false
Used in: Terraform Wrangler Config
Terraform: enable_custom_domains
Wrangler: ENABLE_CUSTOM_DOMAINS

TIP

Allows users to serve images from their own subdomains

`CUSTOM_DOMAIN_FALLBACK_CNAME`

Fallback origin hostname for custom domains (e.g., domains.pixelflare.cc)

Type: string (default: "")
Required: optional
Default: ""
Used in: Wrangler Config
Example: domains.pixelflare.cc
Wrangler: CUSTOM_DOMAIN_FALLBACK_CNAME

TIP

Generated from custom_domain_fallback_subdomain in Terraform

`ANALYTICS_REALTIME_ENABLED`

Enable realtime analytics tracking

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform Wrangler Config
Terraform: analytics_realtime_enabled
Wrangler: ANALYTICS_REALTIME_ENABLED

`ANALYTICS_BATCH_ENABLED`

Enable batch analytics aggregation

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform Wrangler Config
Terraform: analytics_batch_enabled
Wrangler: ANALYTICS_BATCH_ENABLED

Upload Configuration

`ALLOWED_VARIANTS`

JSON array of allowed image variants

Type: json (default: ["w128","w256","w512","w1024","w1536","w2048","thumb","og-image"])
Required: optional
Default: ["w128","w256","w512","w1024","w1536","w2048","thumb","og-image"]
Used in: Terraform Wrangler Config
Example: ["w128","w256","w512","w1024"]
Terraform: allowed_variants
Wrangler: ALLOWED_VARIANTS

`DEFAULT_VARIANT`

Default image variant to serve

Type: string (default: "w1024")
Required: optional
Default: "w1024"
Used in: Terraform Wrangler Config
Example: w1024
Validation: Must be in ALLOWED_VARIANTS
Terraform: default_variant
Wrangler: DEFAULT_VARIANT

`MAX_UPLOAD_BYTES`

Maximum upload size in bytes

Type: number (default: 104857600)
Required: optional
Default: 104857600
Used in: Terraform Wrangler Config
Example: 104857600
Terraform: max_upload_bytes
Wrangler: MAX_UPLOAD_BYTES

TIP

100MB default

Analytics & Retention

`ANALYTICS_RETENTION_DAYS`

Number of days to retain analytics data

Type: number (default: 90)
Required: optional
Default: 90
Used in: Terraform Wrangler Config
Validation: 1-365
Terraform: analytics_retention_days
Wrangler: ANALYTICS_RETENTION_DAYS

Known Issue

Defined but NOT used in cleanup job - uses hard-coded value

`SOFT_DELETE_RETENTION_DAYS`

Number of days to retain soft-deleted images

Type: number (default: 30)
Required: optional
Default: 30
Used in: Terraform Wrangler Config
Validation: 1-365
Terraform: soft_delete_retention_days
Wrangler: SOFT_DELETE_RETENTION_DAYS

Known Issue

Defined but NOT used in cleanup job - uses hard-coded value

`CLEANUP_CRON`

Cron schedule for cleanup job (daily at 1 AM UTC)

Type: string (default: "0 1 * * *")
Required: optional
Default: "0 1 * * *"
Used in: Terraform Wrangler Config
Example: 0 1 * * *
Validation: Valid cron expression
Terraform: cleanup_cron

`ANALYTICS_AGGREGATION_CRON`

Cron schedule for analytics aggregation (daily at 2 AM UTC)

Type: string (default: "0 2 * * *")
Required: optional
Default: "0 2 * * *"
Used in: Terraform Wrangler Config
Example: 0 2 * * *
Validation: Valid cron expression
Terraform: analytics_aggregation_cron

`BACKUP_SYNC_CRON`

Cron schedule for backup sync (daily at 3 AM UTC)

Type: string (default: "0 3 * * *")
Required: optional
Default: "0 3 * * *"
Used in: Terraform Wrangler Config
Example: 0 3 * * *
Validation: Valid cron expression
Terraform: backup_sync_cron

Observability & Logging

`ENABLE_HEALTH_CHECKS`

Enable Cloudflare Health Checks for API endpoint monitoring

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform
Terraform: enable_health_checks

TIP

Monitors /v1/status endpoint every 60s from 6 global regions. Free on all plans.

`ENABLE_NOTIFICATIONS`

Enable notification policies for alerts (requires notification destinations configured)

Type: boolean (default: true)
Required: optional
Default: true
Used in: Terraform
Terraform: enable_notifications

TIP

Free on all plans. Requires email/webhook destinations set up in Cloudflare dashboard first.

`ENABLE_WORKERS_USAGE_NOTIFICATIONS`

Enable Workers usage notifications (must be configured manually in Cloudflare dashboard)

Type: boolean (default: true)
Required: optional
Default: true
Used in: documentation

TIP

Terraform provider does not reliably support this. Configure at: https://dash.cloudflare.com/?to=/:account/notifications/configure

`ENABLE_BILLING_ALERTS`

Enable billing threshold alerts (must be configured manually in Cloudflare dashboard)

Type: boolean (default: true)
Required: optional
Default: true
Used in: documentation

TIP

Terraform provider does not reliably support this. Configure at: https://dash.cloudflare.com/?to=/:account/notifications/configure

`ENABLE_SSL_ALERTS`

Enable SSL expiration alerts (must be configured manually in Cloudflare dashboard)

Type: boolean (default: true)
Required: optional
Default: true
Used in: documentation

TIP

Terraform provider does not reliably support this. Configure at: https://dash.cloudflare.com/?to=/:account/notifications/configure

`NOTIFICATION_EMAILS`

Comma-separated list of Cloudflare notification email integration IDs

Type: string[] (default: [])
Required: optional
Default: []
Used in: Terraform
Example: 1a2b3c4d5e6f7g8h9i0j,2b3c4d5e6f7g8h9i0j1k
Terraform: notification_emails

TIP

Get IDs from: https://dash.cloudflare.com/?to=/:account/notifications/destinations

`NOTIFICATION_WEBHOOK_IDS`

Comma-separated list of Cloudflare webhook integration IDs (Slack, Discord, PagerDuty)

Type: string[] (default: [])
Required: optional
Default: []
Used in: Terraform
Example: webhook_abc123,webhook_def456
Terraform: notification_webhook_ids

TIP

Create webhooks in Cloudflare dashboard for Slack/Discord/custom endpoints.

`PAGERDUTY_INTEGRATION_IDS`

Comma-separated list of PagerDuty integration IDs for critical incidents

Type: string[] (default: [])
Required: optional
Default: []
Used in: Terraform
Example: pagerduty_xyz789
Terraform: pagerduty_integration_ids

TIP

For 24/7 on-call rotations and incident management.

`ENABLE_LOGPUSH`

Enable Cloudflare Logpush to R2 for long-term log retention

Type: boolean (default: false)
Required: optional
Default: false
Used in: deployment-script
Example: true

TIP

Requires Workers Paid plan ($5/month) and R2 API tokens. Setup script will guide you through creating R2 tokens if not provided.

`R2_ACCESS_KEY_ID`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

R2 API token Access Key ID for Logpush

Type: string
Required: optional sensitive
Used in: deployment-script
Example: abc123...

TIP

Required when ENABLE_LOGPUSH=true. Create at Cloudflare Dashboard > R2 > Manage R2 API Tokens with Admin Read & Write permissions.

`R2_SECRET_ACCESS_KEY`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

R2 API token Secret Access Key for Logpush

Type: string
Required: optional sensitive
Used in: deployment-script
Example: xyz789...

TIP

Required when ENABLE_LOGPUSH=true. Create at Cloudflare Dashboard > R2 > Manage R2 API Tokens with Admin Read & Write permissions.

`LOGPUSH_R2_BUCKET`

R2 bucket name for storing logs (separate from app data bucket)

Type: string
Required: optional
Used in: deployment-script
Example: my-bucket-logs

TIP

Optional. Defaults to "{main-bucket-name}-logs" to keep logs separate from app data. Bucket will be created automatically if it doesn't exist.

`LOGPUSH_PATH_PREFIX`

Path prefix for logs within R2 bucket

Type: string (default: "logs/workers")
Required: optional
Default: "logs/workers"
Used in: deployment-script
Example: logs/workers

TIP

Logs stored at: {bucket}/{prefix}/{YYYY}/{MM}/{DD}/file.log

Turnstile

`TURNSTILE_SITE_KEY`

Cloudflare Turnstile site key (public)

Type: string (default: "")
Required: optional
Default: ""
Used in: Terraform Wrangler Config
Example: 1x00000000000000000000AA
Terraform: turnstile_site_key
Wrangler: TURNSTILE_SITE_KEY

TIP

Use test keys for development

`TURNSTILE_SECRET_KEY`

Sensitive Value

Never commit this to version control. Store securely and pass via environment variables or secrets manager.

Cloudflare Turnstile secret key

Type: string (default: "")
Required: optional sensitive
Default: ""
Used in: Terraform Worker Secret
Example: 1x0000000000000000000000000000000AA
Terraform: turnstile_secret_key

TIP

Use test keys for development

Development

`MOCK_AUTH_ENABLED`

Enable mock authentication mode for testing

Type: boolean (default: false)
Required: optional
Default: false
Used in: Wrangler Config
Wrangler: MOCK_AUTH_ENABLED

TIP

Development only - allows X-Mock-Auth header

`VITE_API_URL`

Frontend API URL override (auto-set from DOMAIN for SSR)

Type: string
Required: optional
Used in: Frontend
Example: https://pixelflare.cc/api

TIP

Defaults: http://localhost:8787 (dev), /api (browser prod), https://{DOMAIN}/api (SSR prod). Auto-set in deploy script.

`VITE_DOMAIN`

Frontend URL override (optional - will use window host if not set)

Type: string
Required: optional
Used in: Frontend
Example: pixelflare.cc

`VITE_MOCK_AUTH`

Enable mock authentication in frontend

Type: boolean (default: false)
Required: optional
Default: false
Used in: Frontend

TIP

Development only

`VITE_AUTH_MODE`

Frontend auth mode detection (auto-passed from AUTH_MODE)

Type: string
Required: optional
Used in: Frontend
Validation: none | cloudflare | authjs

TIP

Automatically set from AUTH_MODE during build. Used by SSR config to determine if SSR should be enabled.

`VITE_DISABLE_SSR`

Disable server-side rendering for auth compatibility

Type: boolean
Required: optional
Used in: Frontend
Validation: true | false

TIP

Auto-set based on AUTH_MODE if not specified. Set to true for Cloudflare Access (cookies dont cross subdomains). Set to false for Auth.js (cookies configured with domain attribute).

`VERSION`

Application version, taken from the root package.json

Type: string
Required: optional
Used in: Wrangler Config
Example: 0.1.0
Wrangler: VERSION

TIP

Build metadata, not configuration. Injected by scripts/tasks/09-deploy-workers.sh via wrangler deploy --var, so it is not written into the generated wrangler config. Reported by GET /v1/status.

`GIT_COMMIT`

Git commit SHA the deployed Worker was built from

Type: string
Required: optional
Used in: Wrangler Config
Example: 8ba1357f0c2e4d1a9b3f5e7c8d0a2b4c6e8f0a1b
Wrangler: GIT_COMMIT

TIP

Injected at deploy time like VERSION. Suffixed with -dirty when built from an uncommitted working tree. Reported by GET /v1/status.

`BUNDLE_SHA256`

SHA-256 of the built Worker bundle

Type: string
Required: optional
Used in: Wrangler Config
Example: 517306de157ef8b0a9de0c8a680b6244f9ed5ccab2c33da0dc8c2ffb89f3a451
Wrangler: BUNDLE_SHA256

TIP

Injected at deploy time like VERSION. Vars are runtime metadata rather than bundled code, so this does not alter the hash it describes. Matches the entry in the GitHub release checksums.txt.

Complete .env Template

Copy this template to create your .env file:

bash

# ====================================================================
# Pixelflare Environment Variables
# Auto-generated template - uncomment and fill in values as needed
# ====================================================================

# Authentication & Security
# ---------------------------

# Cloudflare API token for Terraform provider authentication and custom hostname management
CLOUDFLARE_API_TOKEN=your_api_token_here

# Cloudflare account ID for resource creation
CLOUDFLARE_ACCOUNT_ID=your_account_id_here

# Cloudflare zone ID for cache purging and custom hostname management
# CLOUDFLARE_ZONE_ID=zone_id_here

# GitHub OAuth application client ID for Cloudflare Access and Better Auth
# GITHUB_OAUTH_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8

# GitHub OAuth application client secret
# GITHUB_OAUTH_CLIENT_SECRET=your_github_oauth_secret_here

# Google OAuth client ID for Better Auth
# GOOGLE_OAUTH_CLIENT_ID=123456789-abcdefg.apps.googleusercontent.com

# Google OAuth client secret for Better Auth
# GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-...

# Microsoft Entra ID (Azure AD) OAuth client ID for Auth.js
# MICROSOFT_OAUTH_CLIENT_ID=12345678-1234-1234-1234-123456789012

# Microsoft Entra ID (Azure AD) OAuth client secret
# MICROSOFT_OAUTH_CLIENT_SECRET=your_microsoft_oauth_secret_here

# Comma-separated list of allowed email addresses for Access
# ALLOWED_EMAILS=alice@example.com,bob@example.com

# Comma-separated list of allowed email domains for Access
# ALLOWED_EMAIL_DOMAINS=example.com,company.com

# Cloudflare Access team domain (if using existing team)
# ACCESS_TEAM_DOMAIN=myteam

# Authentication mode: none, cloudflare, or authjs
# AUTH_MODE=cloudflare

# Secret key for Auth.js (required when AUTH_MODE=authjs)
# AUTH_SECRET=your-super-secret-random-string-here-min-32-chars

# Cloudflare Access audience tag (generated by Terraform)
# CF_ACCESS_AUD=

# Cloudflare Access certificates URL (generated by Terraform)
# CF_ACCESS_CERTS_URL=https://as93.cloudflareaccess.com/cdn-cgi/access/certs

# Secret for hashing API keys (auto-generated if empty)
# API_HASH_SECRET=""

# Secret for HMAC signing of upload URLs (auto-generated)
# UPLOAD_TOKEN_SECRET=

# AES-256 encryption key for S3 backup credentials (auto-generated)
# BACKUP_ENCRYPTION_KEY=

# Root encryption key for wrapping TMKs (auto-generated)
# ENCRYPTION_ROOT_KEY=

# Infrastructure
# ----------------

# Root domain for all services (used for Auth.js cookie domain)
DOMAIN=pixelflare.cc

# Frontend Pages deployment URL (used for CORS during SSR)
# FRONTEND_HOST=pixflare-production-frontend.pages.dev

# Project name used for resource naming
# PROJECT_NAME=pixflare

# Environment identifier (production, staging, dev)
# ENVIRONMENT=production

# Subdomain for frontend application
# SUBDOMAIN_APP=app

# Subdomain for API
# SUBDOMAIN_API=api

# Subdomain for CDN
# SUBDOMAIN_CDN=cdn

# Public hostname for CDN URLs (generated by Terraform)
CDN_PUBLIC_HOST=pixelflare.cc

# API hostname (generated by Terraform)
API_HOST=pixelflare.cc/api

# Frontend application hostname (generated by Terraform)
APP_HOST=app.pixelflare.cc

# CNAME target for custom domain verification (generated by Terraform)
# CUSTOM_DOMAIN_FALLBACK_CNAME=cdn.pixelflare.cc

# Storage & Resources
# ---------------------

# R2 bucket binding for image storage
R2_BUCKET=

# R2 bucket name for display in status endpoint
# R2_BUCKET_NAME=

# Custom domain for R2 bucket (for image resizing)
# R2_CUSTOM_DOMAIN=r2.pixelflare.cc

# D1 database binding
DB=

# D1 database name for display in status endpoint
# D1_DB_NAME=

# KV namespace binding for caching
KV_CACHE=

# KV namespace ID for display in status endpoint
# KV_CACHE_ID=

# Queue binding for image variant processing
# VARIANT_QUEUE=

# Variant queue name for display in status endpoint
# QUEUE_VARIANT_NAME=

# Queue binding for backup sync
# BACKUP_QUEUE=

# Queue binding for custom domain verification polling
# CUSTOM_DOMAIN_QUEUE=

# Analytics Engine dataset binding
# ANALYTICS=

# Workers AI binding
# AI=

# Vectorize index binding for semantic search
# VECTORIZE=

# Feature Flags
# ---------------

# Enable Cloudflare Access authentication
# ENABLE_ACCESS=true (DEPRECATED)

# Enable Cloudflare Queues for async processing
# ENABLE_QUEUES=true

# Configure custom domain routes for Workers (api.domain.com, cdn.domain.com)
# ENABLE_WORKER_ROUTES=true

# Enable Analytics Engine
# ENABLE_ANALYTICS=true

# Enable Vectorize for semantic image search
# ENABLE_VECTORIZE=false

# Enable AI image classification
# ENABLE_AI_CLASSIFICATION=false

# Enable AI NSFW detection
# ENABLE_AI_NSFW_DETECTION=false

# Enable audit logging for all mutations
# AUDIT_LOG_ENABLED=true

# Enable usage limits and quotas
# USAGE_LIMITS_ENABLED=false

# Enable Stripe billing and subscriptions
# STRIPE_ENABLED=false

# Enable GitHub Sponsors integration for automatic pro plan upgrades
# GITHUB_SPONSORS_CHECK_ENABLED=false

# Stripe secret API key for backend subscription management
# STRIPE_SECRET_KEY=sk_test_... or sk_live_...

# Stripe publishable key for frontend
# STRIPE_PUBLISHABLE_KEY=pk_test_... or pk_live_...

# Stripe webhook signing secret for verifying webhook events
# STRIPE_WEBHOOK_SECRET=whsec_...

# Enable custom domain support (Cloudflare for SaaS)
# ENABLE_CUSTOM_DOMAINS=false

# Fallback origin hostname for custom domains (e.g., domains.pixelflare.cc)
# CUSTOM_DOMAIN_FALLBACK_CNAME=domains.pixelflare.cc

# Enable realtime analytics tracking
# ANALYTICS_REALTIME_ENABLED=true

# Enable batch analytics aggregation
# ANALYTICS_BATCH_ENABLED=true

# Upload Configuration
# ----------------------

# JSON array of allowed image variants
# ALLOWED_VARIANTS=["w128","w256","w512","w1024"]

# Default image variant to serve
# DEFAULT_VARIANT=w1024

# Maximum upload size in bytes
# MAX_UPLOAD_BYTES=104857600

# Analytics & Retention
# -----------------------

# Number of days to retain analytics data
# ANALYTICS_RETENTION_DAYS=90

# Number of days to retain soft-deleted images
# SOFT_DELETE_RETENTION_DAYS=30

# Cron schedule for cleanup job (daily at 1 AM UTC)
# CLEANUP_CRON=0 1 * * *

# Cron schedule for analytics aggregation (daily at 2 AM UTC)
# ANALYTICS_AGGREGATION_CRON=0 2 * * *

# Cron schedule for backup sync (daily at 3 AM UTC)
# BACKUP_SYNC_CRON=0 3 * * *

# Observability & Logging
# -------------------------

# Enable Cloudflare Health Checks for API endpoint monitoring
# ENABLE_HEALTH_CHECKS=true

# Enable notification policies for alerts (requires notification destinations configured)
# ENABLE_NOTIFICATIONS=true

# Enable Workers usage notifications (must be configured manually in Cloudflare dashboard)
# ENABLE_WORKERS_USAGE_NOTIFICATIONS=true

# Enable billing threshold alerts (must be configured manually in Cloudflare dashboard)
# ENABLE_BILLING_ALERTS=true

# Enable SSL expiration alerts (must be configured manually in Cloudflare dashboard)
# ENABLE_SSL_ALERTS=true

# Comma-separated list of Cloudflare notification email integration IDs
# NOTIFICATION_EMAILS=1a2b3c4d5e6f7g8h9i0j,2b3c4d5e6f7g8h9i0j1k

# Comma-separated list of Cloudflare webhook integration IDs (Slack, Discord, PagerDuty)
# NOTIFICATION_WEBHOOK_IDS=webhook_abc123,webhook_def456

# Comma-separated list of PagerDuty integration IDs for critical incidents
# PAGERDUTY_INTEGRATION_IDS=pagerduty_xyz789

# Enable Cloudflare Logpush to R2 for long-term log retention
# ENABLE_LOGPUSH=true

# R2 API token Access Key ID for Logpush
# R2_ACCESS_KEY_ID=abc123...

# R2 API token Secret Access Key for Logpush
# R2_SECRET_ACCESS_KEY=xyz789...

# R2 bucket name for storing logs (separate from app data bucket)
# LOGPUSH_R2_BUCKET=my-bucket-logs

# Path prefix for logs within R2 bucket
# LOGPUSH_PATH_PREFIX=logs/workers

# Turnstile
# -----------

# Cloudflare Turnstile site key (public)
# TURNSTILE_SITE_KEY=1x00000000000000000000AA

# Cloudflare Turnstile secret key
# TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

# Development
# -------------

# Enable mock authentication mode for testing
# MOCK_AUTH_ENABLED=false

# Frontend API URL override (auto-set from DOMAIN for SSR)
# VITE_API_URL=https://pixelflare.cc/api

# Frontend URL override (optional - will use window host if not set)
# VITE_DOMAIN=pixelflare.cc

# Enable mock authentication in frontend
# VITE_MOCK_AUTH=false

# Frontend auth mode detection (auto-passed from AUTH_MODE)
# VITE_AUTH_MODE=

# Disable server-side rendering for auth compatibility
# VITE_DISABLE_SSR=

# Application version, taken from the root package.json
# VERSION=0.1.0

# Git commit SHA the deployed Worker was built from
# GIT_COMMIT=8ba1357f0c2e4d1a9b3f5e7c8d0a2b4c6e8f0a1b

# SHA-256 of the built Worker bundle
# BUNDLE_SHA256=517306de157ef8b0a9de0c8a680b6244f9ed5ccab2c33da0dc8c2ffb89f3a451

Notes

Auto-generated variables are created by Terraform if not provided
Sensitive variables should never be committed to version control
Worker bindings are configured automatically by Terraform
Deprecated variables are kept for backward compatibility but should be replaced
For deployment guides, see Terraform Setup
For more details on specific features, see the Configuration guides

Environment Variables Reference ​

Quick Reference ​

Table of Contents ​

Authentication & Security ​

Infrastructure ​

Storage & Resources ​

Feature Flags ​

Upload Configuration ​

Analytics & Retention ​

Observability & Logging ​

Turnstile ​

Development ​

Usage Guide ​

Where Variables Are Used ​

Setting Variables ​

Authentication & Security ​

CLOUDFLARE_API_TOKEN ​

CLOUDFLARE_ACCOUNT_ID ​

CLOUDFLARE_ZONE_ID ​

GITHUB_OAUTH_CLIENT_ID ​

GITHUB_OAUTH_CLIENT_SECRET ​

GOOGLE_OAUTH_CLIENT_ID ​

GOOGLE_OAUTH_CLIENT_SECRET ​

MICROSOFT_OAUTH_CLIENT_ID ​

MICROSOFT_OAUTH_CLIENT_SECRET ​

ALLOWED_EMAILS ​

ALLOWED_EMAIL_DOMAINS ​

ACCESS_TEAM_DOMAIN ​

AUTH_MODE ​

AUTH_SECRET ​

CF_ACCESS_AUD ​

CF_ACCESS_CERTS_URL ​

API_HASH_SECRET ​

UPLOAD_TOKEN_SECRET ​

BACKUP_ENCRYPTION_KEY ​

ENCRYPTION_ROOT_KEY ​

Infrastructure ​

DOMAIN ​

FRONTEND_HOST ​

PROJECT_NAME ​

ENVIRONMENT ​

SUBDOMAIN_APP ​

SUBDOMAIN_API ​

SUBDOMAIN_CDN ​

CDN_PUBLIC_HOST ​

API_HOST ​

APP_HOST ​

CUSTOM_DOMAIN_FALLBACK_CNAME ​

Storage & Resources ​

R2_BUCKET ​

R2_BUCKET_NAME ​

R2_CUSTOM_DOMAIN ​

DB ​

D1_DB_NAME ​

KV_CACHE ​

KV_CACHE_ID ​

VARIANT_QUEUE ​

QUEUE_VARIANT_NAME ​

BACKUP_QUEUE ​

CUSTOM_DOMAIN_QUEUE ​

ANALYTICS ​

AI ​

VECTORIZE ​

Feature Flags ​

ENABLE_ACCESS ​

ENABLE_QUEUES ​

ENABLE_WORKER_ROUTES ​

ENABLE_ANALYTICS ​

ENABLE_VECTORIZE ​

ENABLE_AI_CLASSIFICATION ​

ENABLE_AI_NSFW_DETECTION ​

AUDIT_LOG_ENABLED ​

USAGE_LIMITS_ENABLED ​

STRIPE_ENABLED ​

GITHUB_SPONSORS_CHECK_ENABLED ​

STRIPE_SECRET_KEY ​

STRIPE_PUBLISHABLE_KEY ​

STRIPE_WEBHOOK_SECRET ​

ENABLE_CUSTOM_DOMAINS ​

CUSTOM_DOMAIN_FALLBACK_CNAME ​

Environment Variables Reference

Quick Reference

Table of Contents

Authentication & Security

Infrastructure

Storage & Resources

Feature Flags

Upload Configuration

Analytics & Retention

Observability & Logging

Turnstile

Development

Usage Guide

Where Variables Are Used

Setting Variables

Authentication & Security

`CLOUDFLARE_API_TOKEN`

`CLOUDFLARE_ACCOUNT_ID`

`CLOUDFLARE_ZONE_ID`

`GITHUB_OAUTH_CLIENT_ID`

`GITHUB_OAUTH_CLIENT_SECRET`

`GOOGLE_OAUTH_CLIENT_ID`

`GOOGLE_OAUTH_CLIENT_SECRET`

`MICROSOFT_OAUTH_CLIENT_ID`

`MICROSOFT_OAUTH_CLIENT_SECRET`

`ALLOWED_EMAILS`

`ALLOWED_EMAIL_DOMAINS`

`ACCESS_TEAM_DOMAIN`

`AUTH_MODE`

`AUTH_SECRET`

`CF_ACCESS_AUD`

`CF_ACCESS_CERTS_URL`

`API_HASH_SECRET`

`UPLOAD_TOKEN_SECRET`

`BACKUP_ENCRYPTION_KEY`

`ENCRYPTION_ROOT_KEY`

Infrastructure

`DOMAIN`

`FRONTEND_HOST`

`PROJECT_NAME`

`ENVIRONMENT`

`SUBDOMAIN_APP`

`SUBDOMAIN_API`

`SUBDOMAIN_CDN`

`CDN_PUBLIC_HOST`

`API_HOST`

`APP_HOST`

`CUSTOM_DOMAIN_FALLBACK_CNAME`

Storage & Resources

`R2_BUCKET`

`R2_BUCKET_NAME`

`R2_CUSTOM_DOMAIN`

`DB`

`D1_DB_NAME`

`KV_CACHE`

`KV_CACHE_ID`

`VARIANT_QUEUE`

`QUEUE_VARIANT_NAME`

`BACKUP_QUEUE`

`CUSTOM_DOMAIN_QUEUE`

`ANALYTICS`

`AI`

`VECTORIZE`

Feature Flags

`ENABLE_ACCESS`

`ENABLE_QUEUES`

`ENABLE_WORKER_ROUTES`

`ENABLE_ANALYTICS`

`ENABLE_VECTORIZE`

`ENABLE_AI_CLASSIFICATION`

`ENABLE_AI_NSFW_DETECTION`

`AUDIT_LOG_ENABLED`

`USAGE_LIMITS_ENABLED`

`STRIPE_ENABLED`

`GITHUB_SPONSORS_CHECK_ENABLED`

`STRIPE_SECRET_KEY`

`STRIPE_PUBLISHABLE_KEY`

`STRIPE_WEBHOOK_SECRET`

`ENABLE_CUSTOM_DOMAINS`

`CUSTOM_DOMAIN_FALLBACK_CNAME`