Environment variables are defined in .env.example. Copy it to create your local configuration:
Database Configuration
POSTGRES_USER
Default: devuser
Used by: PostgreSQL container, all services
Description: PostgreSQL database username for local development.
POSTGRES_PASSWORD
Default: devpass
Used by: PostgreSQL container, all services
Description: PostgreSQL database password for local development.
Never use default credentials in production. Always use strong, randomly generated passwords.
Greeter Service (Go)
CALLER_BASE_URL
Default: http://caller:8081
Used by: greeter service
Description: Base URL for the caller service. Used for inter-service communication.
EXTERNAL_API_URL
Default: https://httpbin.org/get
Used by: greeter service
Description: External API endpoint for testing HTTP requests and response handling.
GREETER_DATABASE_URL
Default: postgresql://devuser:devpass@postgres:5432/greeter_db
Used by: greeter service
Description: PostgreSQL connection string for the greeter service database.
Format:
postgresql://[user]:[password]@[host]:[port]/[database]
Caller Service (Go)
CALLER_DATABASE_URL
Default: postgresql://devuser:devpass@postgres:5432/caller_db
Used by: caller service
Description: PostgreSQL connection string for the caller service database.
Gateway Service (Go)
CUSTOM_LANG_BASE_URL
Default: http://custom-lang-service:3000
Used by: gateway service
Description: Base URL for the custom language service. Used for routing requests to Node.js services.
GATEWAY_DATABASE_URL
Default: postgresql://devuser:devpass@postgres:5432/gateway_db
Used by: gateway service
Description: PostgreSQL connection string for the gateway service database.
Custom Language Service (Node.js)
LANG_DATABASE_URL
Default: postgresql://devuser:devpass@postgres:5432/lang_db
Used by: custom-lang-service
Description: PostgreSQL connection string for the custom language service database.
Auth Service (Node.js)
JWT_SECRET
Default: dev-secret
Used by: auth-service
Description: Secret key for signing and verifying JWT tokens.
In production, use a cryptographically secure random string (minimum 32 characters). Never commit production secrets to version control.
AUTH_DATABASE_URL
Default: postgresql://devuser:devpass@postgres:5432/auth_db
Used by: auth-service
Description: PostgreSQL connection string for the auth service database.
Frontend (React + Vite)
VITE_API_BASE_URL
Default: http://localhost:30081
Used by: frontend
Description: Base URL for API requests from the frontend application. Points to the gateway service.
Note: Vite requires environment variables to be prefixed with VITE_ to be exposed to client-side code.
VITE_USE_MOCK
Default: false
Used by: frontend
Description: Enable Mock Service Worker (MSW) for API mocking in development.
Values:
true - Use MSW handlers for all API callsfalse - Make real API requests to services
When to use: Set to true when developing frontend independently without running backend services.
Environment-Specific Configuration
Local Development
Use the default values in .env.example:
Docker Compose
The docker-compose.yml file references these environment variables. Services use container hostnames (e.g., postgres, greeter) for inter-service communication.
Kubernetes
In Kubernetes deployments, environment variables are managed through:
- ConfigMaps (for non-sensitive configuration)
- Secrets (for sensitive data like passwords and tokens)
- Service discovery (using Kubernetes DNS for service URLs)
See the nixidy modules in deploy/ for Kubernetes configuration.
Security Best Practices
Never commit .env files to version control. The .gitignore file should already exclude .env.
- Use strong passwords - Generate random passwords for production databases
- Rotate secrets regularly - Especially JWT secrets and API keys
- Separate environments - Use different credentials for dev, staging, and production
- Encrypt secrets - Use secret management tools like HashiCorp Vault or AWS Secrets Manager in production
- Limit access - Only grant environment variable access to services that need them
Adding New Environment Variables
When adding new environment variables:
- Add the variable to
.env.example with a descriptive comment
- Document it in this reference page
- Update the service code to read the variable
- Update
docker-compose.yml if using Docker Compose
- Update nixidy modules if deploying to Kubernetes
- Notify team members to update their local
.env files
