Environment Configuration

Purpose and Scope

This document covers the environment variable configuration and management across the TalentSync platform. It details all configuration settings required for the frontend (Next.js), backend (FastAPI), and database (PostgreSQL) services, including build-time versus runtime variable handling, Docker Compose integration, and security best practices.

For information about the Docker images that consume these variables, see Docker Images & Build Process. For deployment automation that sets these variables, see CI/CD Pipeline. For monitoring configuration specifically, see Monitoring & Analytics.

Environment Variable Categories

The TalentSync platform uses environment variables across three main categories, each with distinct loading mechanisms and security considerations.

Build-Time vs Runtime Variables

Sources: docker-compose.yaml1-78 docker-compose.prod.yaml1-66 frontend/Dockerfile9-18

Variable Naming Conventions

Sources: frontend/Dockerfile10-18 docker-compose.prod.yaml38-40

Frontend Environment Configuration

The Next.js frontend requires environment variables for authentication, external service integration, and inter-service communication. Variables are loaded through multiple mechanisms depending on their purpose.

NextAuth Configuration

Sources: docker-compose.yaml58-62 docker-compose.prod.yaml44-48

Authentication Variables

Sources: docker-compose.yaml58-62 frontend/Dockerfile100-125

PostHog Analytics Configuration

PostHog environment variables are unique in that they must be available at both build-time (embedded in client bundle) and runtime (for server-side tracking).

Sources: docker-compose.prod.yaml38-40 frontend/Dockerfile10-18 frontend/instrumentation-client.ts1-12

The PostHog configuration in frontend/instrumentation-client.ts3-11 demonstrates runtime usage:

const key = process.env.NEXT_PUBLIC_POSTHOG_KEY
const apiHost = '/ph'
const uiHost = "https://eu.posthog.com"

posthog.init(key as string, {
  api_host: apiHost,
  ui_host: uiHost,
})

Note that apiHost is hardcoded to /ph to route through a Next.js rewrite proxy, while key and uiHost come from environment variables.

Sources: frontend/instrumentation-client.ts4-11

Inter-Service Communication

The BACKEND_URL variable is critical for frontend-to-backend API calls. In Docker Compose, it uses internal Docker network DNS resolution docker-compose.yaml60:

BACKEND_URL: http://backend:8000 # Internal communication to backend service

Sources: docker-compose.yaml28-29 docker-compose.yaml59-60 docker-compose.prod.yaml24 docker-compose.prod.yaml47-48

Backend Environment Configuration

The FastAPI backend requires environment variables for AI/ML service integration, database connectivity, and external API access.

AI/ML Service API Keys

Sources: docker-compose.yaml24-32

Backend-Specific Environment Variables

The backend Dockerfile sets the NLTK_DATA environment variable at backend/Dockerfile6:

ENV NLTK_DATA=/app/model/nltk_data

This ensures NLP models (lemmatization, stopwords) load correctly from the pre-packaged directory.

Sources: backend/Dockerfile4-6 docker-compose.yaml27-32

Database Environment Configuration

PostgreSQL container configuration uses standard environment variables defined by the postgres:16 Docker image.

PostgreSQL Environment Variables

Sources: docker-compose.yaml4-17 docker-compose.prod.yaml2-14

Database Connection String Construction

The DATABASE_URL variable is constructed from the PostgreSQL variables at docker-compose.yaml28-29:

DATABASE_URL: "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}?schema=public"

This connection string uses:

• Host: db (Docker Compose service name for internal DNS resolution)
• Port: 5432 (default PostgreSQL port)
• Schema: public (Prisma schema namespace)

The same pattern is repeated for the frontend at docker-compose.yaml59

Sources: docker-compose.yaml28-29 docker-compose.yaml59 docker-compose.prod.yaml24 docker-compose.prod.yaml47

Docker Compose Environment Management

Docker Compose provides multiple mechanisms for passing environment variables to containers, used strategically across the TalentSync stack.

Environment Variable Loading Strategy

Sources: docker-compose.yaml7-8 docker-compose.yaml24-25 docker-compose.yaml53-54 docker-compose.prod.yaml37-40

Environment Loading Mechanisms Comparison

Production vs Development Configuration

The production configuration docker-compose.prod.yaml1-66 differs from development docker-compose.yaml1-78 in several key ways:

The production setup uses an external Nginx Proxy Manager network docker-compose.prod.yaml64-66:

networks:
  talentsync_internal_network: 
    driver: bridge
  nginxproxyman_network: 
    external: true
    name: nginx-proxy-manager_nginxproxyman

This allows Nginx to proxy requests to the frontend while keeping the backend isolated on the internal network.

Sources: docker-compose.yaml74-76 docker-compose.prod.yaml61-66

Security Best Practices

.env File Exclusion

The .env file containing sensitive credentials is excluded from version control and Docker builds through multiple mechanisms:

1. Git Exclusion: .gitignore prevents .env from being committed
2. Docker Build Exclusion: frontend/.dockerignore7-12 lists all .env variants:

# Environment files
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

This ensures secrets are never baked into Docker images.

Sources: frontend/.dockerignore7-12

Build-Time vs Runtime Secret Handling

The frontend Dockerfile includes extensive comments on proper secret handling frontend/Dockerfile100-125:

# --- Environment Variable Notes ---
# The Next.js application will require various environment variables at runtime,
# such as those defined in your .env file (e.g., NEXTAUTH_URL, NEXTAUTH_SECRET, DATABASE_URL, etc.).
#
# How to provide them to the Docker container:
# 1. Using 'docker run -e VARNAME=value ...' for each variable.
# 2. Using 'docker run --env-file ./path/to/your/.env.production ...' to pass a file with variable definitions.
#
# Do NOT bake sensitive secrets directly into the Docker image by copying the .env file or using hardcoded ENV instructions for secrets.

Variable Security Classification

Sources: frontend/Dockerfile100-125

Variable Lifecycle Across System

The complete lifecycle of environment variables from development to production deployment:

Sources: docker-compose.yaml1-78 docker-compose.prod.yaml1-66 frontend/Dockerfile1-125 backend/Dockerfile1-33

Environment Variable Reference Table

Complete Variable Inventory

Sources: docker-compose.yaml1-78 docker-compose.prod.yaml1-66 frontend/Dockerfile1-125 backend/Dockerfile1-33