Configuration & Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:The email-platform project utilizes environment variables for configuration, allowing for a clear separation between code and configuration. This approach enables the application to be deployed across different environments (development, testing, production) without code changes. Configuration is managed separately for the API service and the Web service.
The primary mechanism for loading these variables in a development environment is through .env files, which are processed at runtime. In production, these variables are typically injected by container orchestrators like Docker Compose or Kubernetes.
Configuration Loading
The API service uses the dotenv library to load environment variables from a .env file into process.env. The configuration logic is centralized in services/api/src/config.ts.
This file exports a single appConfig object containing all the configuration values. It includes a helper function required to ensure that critical environment variables are present, throwing an error if a required variable is missing.
Sources: services/api/src/config.ts:3-10
The following diagram illustrates the configuration loading flow for the API service.
Sources: services/api/src/config.ts
API Service Configuration (services/api)
The API service has the most extensive configuration, covering database connections, authentication, ports, rate limiting, and more. These are defined in services/api/.env.example and parsed in services/api/src/config.ts.
Core Application
| Variable | Description | Default Value | Required |
|---|---|---|---|
DATABASE_URL | The connection string for the primary PostgreSQL database. | - | Yes |
DATABASE_READ_URL | The connection string for a read-replica database. Falls back to DATABASE_URL. | DATABASE_URL | No |
JWT_SECRET | A strong secret key used for signing JWT tokens. | - | Yes |
HTTP_PORT | The port on which the Fastify HTTP server will listen. | 3001 | No |
SMTP_PORT | The port on which the inbound SMTP server will listen. | 2525 | No |
WEB_URL | The base URL of the frontend web application, used for CORS and redirects. | http://localhost:5173 | No |
TRUST_PROXY | Whether to trust proxy headers (e.g., X-Forwarded-For). Set to true when behind a reverse proxy. | true | No |
Sources: services/api/src/config.ts:12-20, services/api/.env.example:1-5
Default Admin
| Variable | Description | Default Value | Required |
|---|---|---|---|
DEFAULT_ADMIN_EMAIL | The email for the default admin user created on first boot. | admin@example.com | Yes |
DEFAULT_ADMIN_PASSWORD | The password for the default admin user. Should be changed immediately. | changeme | Yes |
Sources: services/api/src/config.ts:23-24, services/api/.env.example:10-11
Rate Limiting & Quotas
| Variable | Description | Default Value | Required |
|---|---|---|---|
RATE_LIMIT_MAX | Max number of API requests per RATE_LIMIT_TIME_WINDOW. | 100 | No |
RATE_LIMIT_TIME_WINDOW | Time window for API rate limiting (e.g., "1 minute"). | 1 minute | No |
SMTP_RATE_WINDOW_MINUTES | Time window in minutes for SMTP rate limits. | 5 | No |
SMTP_RATE_LIMIT_PER_IP | Max inbound emails per IP in the window. | 300 | No |
SMTP_RATE_LIMIT_PER_DOMAIN | Max inbound emails per recipient domain in the window. | 500 | No |
SMTP_RATE_LIMIT_PER_INBOX | Max inbound emails per recipient inbox in the window. | 200 | No |
QUOTA_MESSAGES_PER_INBOX | Maximum number of messages an inbox can hold. | 500 | No |
QUOTA_MESSAGES_PER_DOMAIN | Maximum number of messages a domain can hold across all its inboxes. | 5000 | No |
Sources: services/api/src/config.ts:25-26, services/api/src/config.ts:36-41, services/api/src/config.ts:28-29, services/api/.env.example:13-19
Storage & Attachments
| Variable | Description | Default Value | Required |
|---|---|---|---|
STORAGE_DIR | The local directory for storing attachments if S3 is disabled. | ./storage | Yes |
MAX_ATTACHMENT_BYTES | Maximum size of a single attachment in bytes. | 5242880 (5 MB) | No |
ALLOWED_ATTACHMENT_MIME_PREFIXES | Comma-separated list of allowed MIME type prefixes (e.g., image/). | image/,text/plain,application/pdf | No |
ALLOWED_ATTACHMENT_EXTENSIONS | Comma-separated list of allowed file extensions. | txt,eml,pdf,png,jpg,jpeg | No |
S3_ENABLED | Set to true to use S3 for attachment storage. | false | No |
S3_BUCKET | The S3 bucket name. | "" | No (Yes if S3 enabled) |
S3_REGION | The AWS region for the S3 bucket. | us-east-1 | No (Yes if S3 enabled) |
S3_ENDPOINT | The S3-compatible endpoint URL (for services like MinIO). | - | No |
S3_ACCESS_KEY_ID | S3 Access Key ID. | "" | No (Yes if S3 enabled) |
S3_SECRET_ACCESS_KEY | S3 Secret Access Key. | "" | No (Yes if S3 enabled) |
Sources: services/api/src/config.ts:22, services/api/src/config.ts:27, services/api/src/config.ts:42-43, services/api/src/config.ts:63-70, services/api/.env.example:21-29
Outbound Email
| Variable | Description | Default Value | Required |
|---|---|---|---|
OUTBOUND_ENABLED | Set to true to enable sending emails (e.g., for verification). | false | No |
MAIL_DOMAIN | The domain used for sending system emails. | localhost | No |
MAIL_FROM_NAME | The "From" name for system emails. | TempMail Pro | No |
MAIL_FROM_ADDRESS | The "From" email address for system emails. | noreply@localhost | No |
OUTBOUND_SMTP_HOST | SMTP host for the outbound relay service (e.g., SES, SendGrid). | - | No (Yes if outbound enabled) |
OUTBOUND_SMTP_PORT | SMTP port for the outbound relay service. | - | No (Yes if outbound enabled) |
OUTBOUND_SMTP_USER | SMTP username for the outbound relay service. | - | No (Yes if outbound enabled) |
OUTBOUND_SMTP_PASS | SMTP password for the outbound relay service. | - | No (Yes if outbound enabled) |
OUTBOUND_SMTP_SECURE | Whether to use a secure SMTP connection (TLS). | - | No (Yes if outbound enabled) |
Sources: services/api/src/config.ts:54-58, deployment_guide.md:200-205, services/api/.env.example:31-39
Web Service Configuration (services/web)
The web service configuration is simpler and primarily concerns connecting to the backend API.
| Variable | Description | Default Value | Required |
|---|---|---|---|
VITE_API_BASE | The base URL for the backend API that the frontend will make requests to. | http://localhost:3001 | No |
Sources: services/web/.env.example:1
Production & Deployment Configuration
Docker Compose
For production deployments using docker-compose.prod.yml, environment variables are defined in a root .env file. This file centralizes configuration for multiple services.
Key variables for production include:
DOMAIN: The primary domain name (e.g.,yourdomain.com).ACME_EMAIL: The email address for Let's Encrypt SSL certificate registration.POSTGRES_PASSWORD: The password for the PostgreSQL database.OUTBOUND_*: Variables for configuring a professional outbound email relay service like Amazon SES or SendGrid.
Sources: deployment_guide.md:104-115
Kubernetes
The repository includes an example Kubernetes configuration that separates non-sensitive and sensitive values.
- ConfigMap (
tempmail-config): Stores non-sensitive data like API and web URLs. - Secret (
tempmail-secrets): Stores sensitive data like database URLs and JWT secrets. These values are expected to be Base64 encoded.
This diagram shows how configuration is sourced in different environments.
The k8s/config-secrets.yaml file provides a template for managing secrets in a Kubernetes environment.
# k8s/config-secrets.yaml
apiVersion: v1
kind: Secret
metadata:
name: tempmail-secrets
type: Opaque
data:
# Replace these with actual base64-encoded values
database-url: cG9zdGdyZXNxbDovL3Bvc3RncmVzOnBhc3N3b3JkQHBvc3RncmVzLXNlcnZpY2U6NTQzMi9lbWFpbF9zZXJ2aWNl
jwt-secret: Y2hhbmdlLXRoaXMtaW4tcHJvZHVjdGlvbi10by1hLXN0cm9uZy1zZWNyZXQ=
postgres-password: cGFzc3dvcmQ=
Sources: k8s/config-secrets.yaml:11-23