Why environment variables exist

Environment variables solve a fundamental problem: the same code needs to behave differently in different environments.

# Bad - hardcoded configuration
DATABASE_URL = "postgresql://admin:password123@localhost:5432/myapp"
JWT_SECRET = "super-secret-key-do-not-share"

# Good - read from environment
import os
DATABASE_URL = os.environ["DATABASE_URL"]
JWT_SECRET = os.environ["JWT_SECRET"]

The hardcoded version has three problems: the password is in your source code (visible to anyone with repo access), it always points to localhost (breaks in production), and the JWTWhat is jwt?JSON Web Token - a self-contained, signed token that carries user data (like user ID and role). The server can verify it without a database lookup. Ask AI for more secret is predictable (anyone who reads your code can forge tokens).

Setting env vars per platform

Each platform has its own approach.

Railway

# CLI
railway variables set DATABASE_URL="postgresql://..."
railway variables set JWT_SECRET="$(openssl rand -hex 32)"

# Or use the Railway dashboard - Variables tab on your service

Railway also supports reference variables: if you create a Postgres database on Railway, it automatically injects DATABASE_URL into your app service.

Fly.io

# Fly secrets are encrypted and never visible after being set
fly secrets set DATABASE_URL="postgresql://..."
fly secrets set JWT_SECRET="$(openssl rand -hex 32)"

# List secrets (shows names only, not values)
fly secrets list

Render

Render supports environment groups, named collections of env vars you can share across services. This is useful when your APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more and your worker process need the same database URL.

Validating config at startup with pydantic-settings

Raw os.getenv() calls scatter your configuration across the codebase and provide no validation. pydantic-settings centralizes everything.

from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    database_url: str
    jwt_secret: str = Field(min_length=32)
    debug: bool = False
    allowed_origins: list[str] = ["https://myapp.com"]

    model_config = {"env_file": ".env"}

# This crashes at import time if DATABASE_URL is missing
settings = Settings()

This gives you three things os.getenv() does not:

1. Crash-early validation: if database_url is missing, the app fails immediately with a clear error, not 10 minutes later when the first database query runs
2. Type coercionWhat is type coercion?JavaScript automatically converting a value from one type to another during an operation, like turning a string into a number for subtraction. Ask AI for more: debug is automatically parsed from the string "true" to the boolean True
3. Single source of truth: every config value is defined in one class, not scattered across files

The .env.example pattern

Your .env file is in .gitignore (it must be). But new developers need to know which variables to set. The solution is .env.example:

# .env.example - committed to git, documents required variables
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
JWT_SECRET=generate-a-32-char-secret-here
DEBUG=true
ALLOWED_ORIGINS=http://localhost:3000
SENTRY_DSN=

This file uses placeholder values, not real secrets. It serves as documentation: "here are the variables this app needs."

Secret rotation and access control

Secrets are not set-and-forget. They need maintenance.

# Danger - logging the settings object exposes secrets
logger.info(f"Starting with config: {settings}")

# Safe - log only non-sensitive fields
logger.info(f"Starting with debug={settings.debug}, origins={settings.allowed_origins}")

Quick reference