environment-setup

name	environment-setup
description	Environment variable patterns, config file validation, and setup verification for new project scaffolding.

Environment Setup Protocol

Rules for managing environment variables, secrets, and local configuration across any stack.

Core Principle

Every project should have a template/example config file checked into source control, and the actual config file (with real values) gitignored. The developer copies the template and fills in real values locally.

Common Patterns by Stack

Stack	Template File	Actual File	Gitignored
Node.js / Python	.env.example	.env	.env
Java / Spring	application-example.yml	application.yml	application.yml
Go	config.example.yaml	config.yaml	config.yaml
Docker	docker-compose.override.example.yml	docker-compose.override.yml	docker-compose.override.yml

Phase 1: Initial Setup

During scaffolding, before the first build/run:

1. Copy the template — cp .env.example .env (or equivalent for your stack).
2. Fill minimum required values — database URL, secret keys, API credentials.
3. Verify .gitignore — confirm the actual config file is excluded.
4. Test the build — run the dev server to validate config is loaded correctly.

Environment Variable Validation

Always validate required environment variables at startup. Fail fast with clear error messages rather than crashing with cryptic errors later.

# Pseudocode — adapt to your language/framework

required_vars = ["DATABASE_URL", "SECRET_KEY", "API_BASE_URL"]

for var in required_vars:
    if var not set or empty:
        raise Error("Missing required environment variable: {var}")

Most frameworks have libraries for this (e.g., Zod + dotenv for Node, pydantic-settings for Python, Spring @ConfigurationProperties for Java).

Security Best Practices

Local development:

• Use real credentials for local services (database, SMTP, etc.).
• Never commit the actual config file.
• Use app-specific passwords where available (not your personal account password).

Production:

• Never use .env files in production. Use the platform's secret management (e.g., cloud provider secrets manager, Kubernetes secrets, CI/CD variables).
• Rotate credentials periodically.
• Use least-privilege service accounts.

Team sharing:

• Keep the template file updated with all required variables (use placeholder values).
• Document where to obtain each credential (e.g., "Get from team password manager" or "Generate at https://...").
• Never share secrets via chat, email, or committed files.

Troubleshooting

Symptom	Likely Cause	Fix
App crashes on startup	Missing required env var	Check template file, add missing vars to local config
"Connection refused" errors	Service not running or wrong credentials	Verify the service is running, check URL and credentials
"Module not found" at runtime	Missing runtime dependency	Install the dependency (may not be caught by type checkers)
Auth/login fails	Missing or incorrect secret key	Regenerate and set the secret key in local config