.env.example

# KoNote Web — Environment Variables
# ====================================
# Copy this file to .env and fill in your values.
# See docs/getting-started.md for detailed setup instructions.

# ==============================================================================
# REQUIRED — KoNote will not start without these
# ==============================================================================

# Django secret key — used for session security and CSRF protection
# Generate with: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
SECRET_KEY=REPLACE_THIS_run_the_command_above_to_generate

# PII encryption key — encrypts client names, emails, birth dates in the database
# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# WARNING: If you lose this key, all encrypted client data is UNRECOVERABLE
# Back up this key separately from your database backups!
FIELD_ENCRYPTION_KEY=REPLACE_THIS_run_the_command_above_to_generate

# Email hash key — used to create keyed HMAC hashes of participant emails
# Required in production (app will not start without it)
# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
EMAIL_HASH_KEY=REPLACE_THIS_run_the_command_above_to_generate

# Main database connection — stores clients, programs, notes, settings
# Format: postgresql://username:password@host:port/database
DATABASE_URL=postgresql://konote:REPLACE_THIS_WITH_YOUR_PASSWORD@localhost:5432/konote

# Audit database connection — stores immutable audit logs (separate for security)
# Format: postgresql://username:password@host:port/database
AUDIT_DATABASE_URL=postgresql://audit_writer:REPLACE_THIS_WITH_YOUR_PASSWORD@localhost:5433/konote_audit

# ==============================================================================
# DOCKER COMPOSE — Only needed if using docker-compose.yml
# ==============================================================================

# Main database credentials (used by docker-compose to create the database)
POSTGRES_USER=konote
POSTGRES_PASSWORD=REPLACE_THIS_WITH_A_SECURE_PASSWORD
POSTGRES_DB=konote

# Audit database credentials (used by docker-compose to create the audit database)
AUDIT_POSTGRES_USER=audit_writer
AUDIT_POSTGRES_PASSWORD=REPLACE_THIS_WITH_ANOTHER_PASSWORD
AUDIT_POSTGRES_DB=konote_audit

# ==============================================================================
# AUTHENTICATION
# ==============================================================================

# Auth mode: "local" for username/password, "azure" for Azure AD SSO
# Most organisations start with "local" and add Azure AD later
AUTH_MODE=local

# Azure AD settings — only required if AUTH_MODE=azure
# Get these from your Azure Portal > App Registrations
AZURE_CLIENT_ID=
AZURE_CLIENT_SECRET=
AZURE_TENANT_ID=
AZURE_REDIRECT_URI=https://REPLACE_THIS_WITH_YOUR_DOMAIN.com/auth/callback/

# ==============================================================================
# OPTIONAL SETTINGS
# ==============================================================================

# Allowed hosts — domains that can access the application (comma-separated)
# For local development: localhost,127.0.0.1
# For production: your-domain.com,www.your-domain.com
ALLOWED_HOSTS=localhost,127.0.0.1

# CSRF trusted origins — required for HTTPS form submissions on custom domains
# Use full origins with https:// (comma-separated)
# Example: https://your-domain.com,https://www.your-domain.com
CSRF_TRUSTED_ORIGINS=

# Domain for Caddy TLS certificate (production Docker deployment only)
# Set this to your public domain name
DOMAIN=localhost

# Debug mode — set to False in production (shows detailed errors if True)
# DEBUG=False

# ==============================================================================
# EXPORTS AND NOTIFICATIONS
# ==============================================================================

# Export file storage directory (default: system temp folder + konote_exports)
# Must be outside the web root. On Docker Compose (OVHcloud VPS), /tmp/konote_exports is fine.
# SECURE_EXPORT_DIR=/path/to/exports

# Export download link expiry in hours (default: 24)
# SECURE_EXPORT_LINK_EXPIRY_HOURS=24

# Delay before large exports (100+ clients or including notes) can be downloaded, in minutes (default: 10)
# Gives admins time to review and revoke if needed. Set to 0 for instant download.
# ELEVATED_EXPORT_DELAY_MINUTES=10

# Who receives export notification emails (comma-separated)
# If not set, notifications go to all active admin users.
# Use this to send notifications to a privacy officer or ED instead of the tech admin.
# EXPORT_NOTIFICATION_EMAILS=privacy@agency.ca,ed@agency.ca

# SMTP email settings — required in production for:
#   - Export notifications (admin alerted when large exports are created)
#   - Erasure workflow (program managers notified when approval needed)
#   - Password reset emails (if using local auth)
# If not configured, exports still work but admin notifications fail silently.
#
# Resend.com (recommended — free tier: 100 emails/day, 3,000/month):
# EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
# EMAIL_HOST=smtp.resend.com
# EMAIL_PORT=587
# EMAIL_USE_TLS=True
# EMAIL_HOST_USER=resend
# EMAIL_HOST_PASSWORD=re_your_resend_api_key_here
# DEFAULT_FROM_EMAIL=KoNote <noreply@yourdomain.ca>
#
# Microsoft 365 (alternative):
# EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
# EMAIL_HOST=smtp.office365.com
# EMAIL_PORT=587
# EMAIL_HOST_USER=notifications@yourorg.ca
# EMAIL_HOST_PASSWORD=your-smtp-password
# EMAIL_USE_TLS=True
# DEFAULT_FROM_EMAIL=KoNote <notifications@yourorg.ca>

# ==============================================================================
# DEMO / EVALUATION
# ==============================================================================

# Demo mode — shows quick-login buttons on login page and seeds demo data (5 users, 10 clients)
# Values: true, 1, yes (case-insensitive). Default: false
# DEMO_MODE=true

# Demo email base — if set, demo users get tagged emails (e.g. user+demo-admin@gmail.com)
# Useful for testing email delivery. Uses Gmail's +tag feature so all land in one inbox.
# DEMO_EMAIL_BASE=user@gmail.com

# KoNote mode — controls startup security check behaviour
# 'production' (default): blocks startup if critical security checks fail
# 'demo': warns but allows startup for evaluation
# NOTE: This is different from DEMO_MODE. DEMO_MODE controls demo data seeding.
#       KONOTE_MODE controls whether security check failures block startup.
# KONOTE_MODE=production

# Skip startup seed — provisions a blank instance without default metrics,
# templates, event types, or demo data. Useful for new production environments
# that should be configured manually later.
# Values: true, 1, yes (case-insensitive). Default: false
# KONOTE_SKIP_SEED=true

# ==============================================================================
# AI FEATURES (OPTIONAL)
# ==============================================================================

# OpenRouter API key — enables AI-powered Goal Builder, metric suggestions, and
# outcome improvement. To activate AI features, you need BOTH:
#   1. Set OPENROUTER_API_KEY below
#   2. Enable the "ai_assist" feature toggle in Admin → Settings
# Features are hidden from the UI when either is missing.
# OPENROUTER_API_KEY=sk-or-...
# OPENROUTER_MODEL=qwen/qwen3.5-35b-a3b

# Optional custom provider for participant-data insights.
# Use this for the self-hosted open-source path when participant suggestion
# categorisation or other participant-text analysis must stay on infrastructure
# managed by the KoNote operator. Leave blank to use OpenRouter for any
# remaining de-identified insights traffic.
# Remote providers MUST use HTTPS. Local self-hosted endpoints may use HTTP.
# INSIGHTS_API_BASE=http://localhost:11434/v1
# INSIGHTS_API_KEY=
# INSIGHTS_MODEL=llama3
# Optional allowlist for approved remote hosts when participant-data AI is enabled.
# Supports exact hosts or wildcards like *.agency-ai.ca
# INSIGHTS_ALLOWED_HOSTS=ai.agency.ca,*.agency-ai.ca

# ==============================================================================
# OPS / AUTOMATION (Docker ops sidecar)
# ==============================================================================
# The ops container handles automated backups, disk monitoring, health reports,
# Docker cleanup, and backup verification. It starts automatically with
# `docker compose up -d` — no host-level cron jobs needed.
#
# All settings below are optional. Backups run by default with no configuration.

# Backup retention in days (main DB / audit DB)
# BACKUP_RETENTION_DAYS=30
# AUDIT_RETENTION_DAYS=90

# Dead man's switch — ping this URL after every successful backup.
# If the ping stops arriving, your monitoring service alerts you.
# Works with: UptimeRobot push monitors, Healthchecks.io, Cronitor, Uptime Kuma.
# HEALTHCHECK_PING_URL=https://hc-ping.com/your-uuid-here

# Alert webhook — receives a plain-text POST on backup failure or disk warning.
# Compatible with: ntfy.sh, Slack incoming webhooks, UptimeRobot push monitors.
# ALERT_WEBHOOK_URL=

# Disk usage alert threshold (percentage, default: 80)
# DISK_THRESHOLD=80

# Health report recipients — comma-separated email addresses.
# Daily health email sent at 7 AM with operational status (no PII).
# Requires EMAIL_HOST to be configured (same SMTP settings as Django).
# If not set, the health report logs to the container's stdout instead.
# OPS_HEALTH_REPORT_TO=admin@agency.ca

# Disable Docker system prune (default: true = prune runs weekly on Sundays)
# OPS_PRUNE_ENABLED=true

# Disable weekly backup verification (default: true = test restore runs Sundays)
# OPS_VERIFY_BACKUPS=true

# KoNote version tag — included in health reports. Set during build or deploy.
# If not set, reports show "dev".
# KONOTE_VERSION=v1.0.0

# ==============================================================================
# NOTES
# ==============================================================================
#
# Security reminders:
# - Never commit this file to version control with real values
# - Use different keys for development, staging, and production
# - Rotate FIELD_ENCRYPTION_KEY every 90 days (see docs/security-operations.md)
# - Back up FIELD_ENCRYPTION_KEY in a secure location separate from database backups
#
# Getting errors?
# - KoNote.E001: FIELD_ENCRYPTION_KEY missing or invalid — generate a new one above
# - KoNote.E002: Security middleware missing — check settings.py MIDDLEWARE
# - Database connection refused: Check PostgreSQL is running and credentials match
#
# Full documentation: docs/getting-started.md