Skip to content

Environment Variables

This document describes the environment variables used in the tracker REST API system based on the actual configuration.

Core Application Variables

API Configuration

  • API_V1_STR - API version prefix
  • Default: /api/v1

  • Used for API route prefixing

  • PROJECT_NAME - Project name for documentation

  • Default: Tracker API

  • ENVIRONMENT - Application environment

  • Values: development, testing, production

  • Default: development

  • TESTING - Flag to indicate test mode

  • Values: true, false
  • Default: false

Database Configuration

  • POSTGRES_SERVER - PostgreSQL server hostname
  • Default: localhost

  • Example: db (Docker service name)

  • POSTGRES_USER - PostgreSQL username

  • Default: postgres

  • Example: tracker

  • POSTGRES_PASSWORD - PostgreSQL password

  • Default: postgres

  • Required in production

  • POSTGRES_DB - PostgreSQL database name

  • Default: tracker

  • POSTGRES_PORT - PostgreSQL port

  • Default: 5432

Authentication & Security

  • SECRET_KEY - JWT signing secret
  • Default: your-secret-key-for-jwt

  • Should be a long, random string in production

  • ACCESS_TOKEN_EXPIRE_MINUTES - JWT access token expiration time

  • Default: 240 (4 hours)

  • Configured to reduce likelihood of expiry during sleep

  • REFRESH_TOKEN_EXPIRE_DAYS - JWT refresh token expiration time

  • Default: 7 days

  • JWT_ISSUER - JWT issuer identifier

  • Default: tracker-api

  • JWT_AUDIENCE - JWT audience identifier

  • Default: tracker-clients

  • ALGORITHM - JWT signing algorithm

  • Default: HS256

Single Sign-On (SSO)

Both are optional and independent -- the login page only shows a provider's button once its client ID is set (see active_provider_display_names() in app/core/oidc.py, also used to tell invited users which SSO options are available instead of their generated password).

  • GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET - Google OAuth app credentials
  • Default: unset (Google login hidden)
  • MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET - Microsoft Entra ID (Azure AD) app credentials
  • Default: unset (Microsoft login hidden)
  • MICROSOFT_TENANT_ID - Microsoft tenant to authenticate against
  • Default: common (personal + work/school accounts)

Local development: set these in .env -- compose.yml passes them straight through to the dev container.

Staging/production: these are real, externally-issued OAuth credentials, not values Terraform should generate. They're created out-of-band with aws secretsmanager create-secret/put-secret-value, and only referenced by ARN from Terraform (google_client_id_secret_arn/google_client_secret_secret_arn in infra/envs/staging/variables.tf), unlike SECRET_KEY/the database and Redis passwords, which Terraform generates and manages directly (see the Terraform Deployment Guide). As of this writing, only Google SSO is wired up in staging Terraform -- Microsoft's variables/secret wiring don't exist yet, so MICROSOFT_CLIENT_ID/MICROSOFT_CLIENT_SECRET would need the same treatment added before Microsoft login could work anywhere but local dev.

Related, non-secret settings used for building SSO redirect URLs and invite-email login links:

  • FRONTEND_URL - base URL of the user-facing frontend
  • Default: http://localhost:3100
  • ADMIN_URL - base URL of the admin panel
  • Default: http://localhost:3102

CORS Configuration

  • CORS_ORIGINS - Allowed CORS origins (hardcoded in config)
  • Includes: http://localhost:3000, http://localhost:8080, http://localhost:8100
  • Production: https://tracker-admin.glimpse.technology, https://tracker.glimpse.technology

Dragonfly/Redis Configuration

  • REDIS_HOST - Dragonfly hostname
  • Default: dragonfly

  • Example: 192.168.100.1 (local development)

  • REDIS_PORT - Dragonfly port

  • Default: 6379

  • REDIS_USERNAME - Dragonfly username (optional)

  • Used for AWS Valkey compatibility

  • Default: None

  • REDIS_PASSWORD - Dragonfly password

  • Default: Empty string

  • Required in production

  • REDIS_CLUSTER_MODE - Enable cluster mode

  • Values: true, false

  • Default: false

  • REDIS_CACHE_TTL - Cache time-to-live in seconds

  • Default: 3600 (1 hour)

Dragonfly TLS Configuration

  • REDIS_TLS_ENABLED - Enable TLS encryption
  • Values: true, false

  • Default: false

  • REDIS_TLS_CERT_REQS - TLS certificate requirements

  • Default: none

  • Values: none, optional, required

  • REDIS_TLS_CA_CERTS_FILE - Path to CA certificates file

  • Optional for TLS verification

  • REDIS_TLS_CERTFILE - Path to client certificate file

  • Optional for client certificate authentication

  • REDIS_TLS_KEYFILE - Path to client key file

  • Optional for client certificate authentication

Static Files & External URLs

  • STATIC_DIR - Directory for static files

  • Default: ../static (relative to app directory)

  • EXTERNAL_BASE_URL - External base URL for the API

  • Default: http://localhost:8100

  • Example: https://tracker.glimpse.technology

  • API_URL - API URL for external access

  • Used in production for frontend services
  • Example: https://tracker.glimpse.technology

Development & Testing

  • DEBUG - Enable debug mode
  • Values: true, false

  • Used in local development

  • DEBUG_WAIT_FOR_CLIENT - Wait for debugger client (Docker)

  • Values: true, false
  • Default: false

Docker Environment

Database Configuration

  • POSTGRES_SERVER - PostgreSQL server hostname
  • Example: db (service name in Docker Compose)
  • POSTGRES_USER - PostgreSQL username
  • Default: tracker
  • POSTGRES_PASSWORD - PostgreSQL password (required)
  • POSTGRES_DB - PostgreSQL database name
  • Default: tracker
  • POSTGRES_PORT - PostgreSQL port
  • Default: 5432

Dragonfly Configuration

  • REDIS_HOST - Dragonfly hostname
  • Example: dragonfly (service name in Docker Compose)
  • REDIS_PORT - Dragonfly port
  • Default: 6379
  • REDIS_USERNAME - Dragonfly username (optional)
  • REDIS_PASSWORD - Dragonfly password (required)
  • REDIS_CLUSTER_MODE - Enable cluster mode
  • Default: false
  • REDIS_CACHE_TTL - Cache time-to-live in seconds
  • Default: 3600
  • REDIS_TLS_ENABLED - Enable TLS encryption
  • Default: false
  • REDIS_TLS_CERT_REQS - TLS certificate requirements
  • Default: none
  • REDIS_TLS_CA_CERTS_FILE - Path to CA certificates file
  • REDIS_TLS_CERTFILE - Path to client certificate file
  • REDIS_TLS_KEYFILE - Path to client key file

Application Configuration

  • SECRET_KEY - JWT signing secret (required)
  • DEBUG_WAIT_FOR_CLIENT - Wait for debugger client
  • Default: false
  • EXTERNAL_BASE_URL - External base URL for the API
  • Example: https://tracker.glimpse.technology
  • API_URL - API URL for frontend services
  • Example: http://dev:8000 (development)
  • Example: https://tracker.glimpse.technology (production)

Example Configuration Files

.env (Development)

# Database
POSTGRES_USER=tracker
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=tracker

# Security
SECRET_KEY=your-very-long-random-secret-key

# Dragonfly
REDIS_PASSWORD=your-redis-password
REDIS_USERNAME=
REDIS_CLUSTER_MODE=false
REDIS_CACHE_TTL=3600
REDIS_TLS_ENABLED=false
REDIS_TLS_CERT_REQS=none

# Development
DEBUG_WAIT_FOR_CLIENT=false

.env (Production)

# Database
POSTGRES_SERVER=db
POSTGRES_USER=tracker
POSTGRES_PASSWORD=very-secure-production-password
POSTGRES_DB=tracker
POSTGRES_PORT=5432

# Security
SECRET_KEY=very-long-random-production-secret-key

# Dragonfly
REDIS_HOST=dragonfly
REDIS_PORT=6379
REDIS_PASSWORD=very-secure-redis-password
REDIS_USERNAME=
REDIS_CLUSTER_MODE=false
REDIS_CACHE_TTL=3600
REDIS_TLS_ENABLED=false
REDIS_TLS_CERT_REQS=none

# External URLs
EXTERNAL_BASE_URL=https://tracker.glimpse.technology
API_URL=https://tracker.glimpse.technology

Security Considerations

!!! warning "Security Best Practices" - Never commit .env files to version control - Use strong, unique values for SECRET_KEY - Rotate secrets regularly in production - Use environment-specific configurations - Limit CORS origins to trusted domains only

Loading Environment Variables

The application loads environment variables in the following order:

  1. System environment variables
  2. .env.local file (development)
  3. .env file (fallback)
  4. Default values in code

This allows for flexible configuration across different environments while maintaining security.