Environment Variables

Managing environment variables securely and predictably is crucial for any application.

The .env File

When you scaffold a new project with create-harpia-app, a .env file is automatically generated at the root of your project. The APP_ID is filled with a random hex string, and MODE and DB_URL are set according to the choices you made during project creation.

The full template contains the following groups of variables:

# Application
APP_ID=                          # Auto-generated unique identifier for this instance
ENV=development                  # Runtime environment: development | test | production
PORT=3000                        # Port the HTTP server listens on
MODE=                            # Application mode: api | fullstack
JWT_SECRET=harpia_jwt_secret_key # Secret key for signing JWT tokens
TELEMETRY_API_KEY=               # API key for the Harpia Telemetry service

# Database (PostgreSQL / MySQL)
# DB_PROVIDER=<postgresql|mysql>
# DB_USER=""
# DB_PASS=""
# DB_PORT=""
# DB_NAME=""
# DB_HOST=""
# DB_URL=${DB_PROVIDER}://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}

# Database (SQLite)
# DB_URL="file:./prisma/dev.db"

# Redis
REDIS_HOST=localhost
REDIS_USER=
REDIS_PASS=
REDIS_PORT=6379

# Mailer
SMTP_HOST=<YOUR_SMTP_HOST>
SMTP_PORT=<YOUR_SMTP_PORT>
SMTP_USER=<YOUR_SMTP_USER>
SMTP_PASSWORD=<YOUR_SMTP_PASSWORD>
SMTP_SECURE=<IF_SHOULD_USE_SSL>

# Amazon S3
S3_KEY=<YOUR_S3_KEY>
S3_SECRET=<YOUR_S3_SECRET>
S3_BUCKET=<YOUR_S3_BUCKET>
S3_REGION=<YOUR_S3_REGION>
S3_ENDPOINT=https://s3.${S3_REGION}.amazonaws.com
S3_BUCKET_PATH=https://${S3_BUCKET}.s3.${S3_REGION}.amazonaws.com/

[!TIP] Keep sensitive variables (like JWT_SECRET, SMTP_PASSWORD, and S3_SECRET) out of version control. The .gitignore generated by create-harpia-app already excludes the .env file. Commit only your .env.example with placeholder values.