Environment Configuration

The AdonisJS Starter Kit uses environment variables for configuration. This guide covers all available variables and their usage.

Environment File

Environment variables are stored in .env files:

app/
├── .env.example          # Template with all variables
├── .env                  # Your local configuration (gitignored)
└── .env.production       # Production overrides (optional)

Never commit .env files to version control. Only .env.example should be tracked.

Getting Started

Create your local environment file:

cd apps/web
cp .env.example .env

Generate application key:

node ace generate:key

The APP_KEY is used for encryption and must be kept secret in production.

Core Configuration

Application Settings

NODE_ENV

string

default:"development"

required

Application environment. Controls behavior, logging, and optimizations.

Show Options

development - Local development with hot reloading
production - Optimized for production deployment
test - Used during automated testing

PORT

number

default:"3333"

required

Port number the application listens on.

PORT=3333

HOST

string

default:"localhost"

required

Host address to bind to. Use 0.0.0.0 to accept connections from any network interface.

# Development
HOST=localhost

# Production (Docker)
HOST=0.0.0.0

APP_KEY

string

required

Secret key for encryption, sessions, and CSRF tokens. Generate with node ace generate:key.

APP_KEY=your-generated-key-here

Must be unique per application and kept secret. Never share or commit this value.

LOG_LEVEL

string

default:"info"

Logging verbosity level.

Show Levels

trace - Most verbose
debug - Debug information
info - General information (default)
warn - Warnings
error - Errors only
fatal - Fatal errors only

# Development
LOG_LEVEL=debug

# Production
LOG_LEVEL=info

string

default:"UTC"

Application timezone. Affects date/time operations.

TZ=UTC
# or
TZ=America/New_York

Session Configuration

SESSION_DRIVER

string

default:"cookie"

required

Session storage driver.

Show Options

cookie - Store sessions in encrypted cookies (default)
memory - In-memory storage (development only)
redis - Redis-backed sessions (recommended for production)
database - Database-backed sessions

SESSION_DRIVER=cookie

Database Configuration

PostgreSQL Settings

DB_HOST

string

default:"127.0.0.1"

required

PostgreSQL server hostname or IP address.

# Local development
DB_HOST=127.0.0.1

# Docker
DB_HOST=pgsql

# Remote server
DB_HOST=db.example.com

DB_PORT

number

default:"5432"

required

PostgreSQL server port.

DB_PORT=5432

DB_USER

string

default:"root"

required

Database username.

DB_USER=root

DB_PASSWORD

string

default:"root"

required

Database password.

DB_PASSWORD=root

Use strong passwords in production. Consider using secrets management.

DB_DATABASE

string

default:"app"

required

Database name.

DB_DATABASE=app

Connection String Alternative

You can also use a connection string:

DATABASE_URL=postgresql://user:password@host:port/database?ssl=true

Connection strings are useful for cloud providers like Railway, Render, or Heroku.

Email Configuration

The starter kit supports two email methods:

Resend (Recommended for Production)

RESEND_API_KEY

string

API key from Resend.

RESEND_API_KEY=re_123456789

EMAIL_FROM

string

required

Default “from” email address.

[email protected]

SMTP (Development with Mailpit)

SMTP_HOST

string

default:"localhost"

SMTP server hostname.

# Mailpit (development)
SMTP_HOST=localhost

# Production SMTP
SMTP_HOST=smtp.gmail.com

SMTP_PORT

number

default:"1025"

SMTP server port.

# Mailpit
SMTP_PORT=1025

# Gmail
SMTP_PORT=587

SMTP_USERNAME

string

SMTP authentication username.

[email protected]

SMTP_PASSWORD

string

SMTP authentication password.

SMTP_PASSWORD=your-password

SMTP_SECURE

number

default:"0"

Use TLS/SSL for SMTP connection.

# Disabled (Mailpit)
SMTP_SECURE=0

# Enabled (production)
SMTP_SECURE=1

SMTP_REJECTUNAUTHORIZED

boolean

default:"false"

Reject unauthorized certificates.

# Development
SMTP_REJECTUNAUTHORIZED=false

# Production
SMTP_REJECTUNAUTHORIZED=true

Email Configuration Examples

Mailpit (Development)
Resend (Production)
Gmail SMTP

SMTP_HOST=localhost
SMTP_PORT=1025
[email protected]
SMTP_PASSWORD=XXX
SMTP_SECURE=0
SMTP_REJECTUNAUTHORIZED=false
[email protected]

RESEND_API_KEY=re_your_api_key_here
[email protected]

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=your-app-password
SMTP_SECURE=1
SMTP_REJECTUNAUTHORIZED=true
[email protected]

OAuth Configuration

Google OAuth

GOOGLE_CLIENT_ID

string

Google OAuth 2.0 client ID from Google Cloud Console.

GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com

GOOGLE_CLIENT_SECRET

string

Google OAuth 2.0 client secret.

GOOGLE_CLIENT_SECRET=your-secret-here

Create OAuth App

Go to Google Cloud Console
Create a new project or select existing
Enable Google+ API
Create OAuth 2.0 credentials

Configure Redirect URIs

Add authorized redirect URIs:

http://localhost:3333/auth/google/callback
https://yourdomain.com/auth/google/callback

Copy Credentials

Copy the Client ID and Client Secret to your .env file.

Storage Configuration

DRIVE_DISK

string

default:"fs"

Default storage disk driver.

Show Options

fs - Local filesystem storage
s3 - Amazon S3 compatible storage
gcs - Google Cloud Storage

# Development
DRIVE_DISK=fs

# Production
DRIVE_DISK=s3

S3 Configuration (Optional)

For cloud storage:

S3_KEY=your-access-key
S3_SECRET=your-secret-key
S3_BUCKET=your-bucket-name
S3_REGION=us-east-1
S3_ENDPOINT=https://s3.amazonaws.com

Rate Limiting

LIMITER_STORE

string

default:"database"

Storage backend for rate limiting.

Show Options

memory - In-memory storage (single server only)
database - Database-backed (recommended)
redis - Redis-backed (best for multi-server)

LIMITER_STORE=database

Frontend Configuration

VITE_API_URL

string

default:"http://localhost:3333"

API URL for frontend requests. Used by Vite during development.

# Development
VITE_API_URL=http://localhost:3333

# Production
VITE_API_URL=https://api.yourdomain.com

Docker Compose Variables

Project Configuration

COMPOSE_PROJECT_NAME

string

Docker Compose project name. Prefixes all container names.

COMPOSE_PROJECT_NAME=myapp

Results in containers like:

myapp_web
myapp_pgsql
myapp_pgadmin

PgAdmin Configuration

PGADMIN_MAIL

string

default:"[email protected]"

PgAdmin login email.

[email protected]

PGADMIN_PW

string

default:"secret"

PgAdmin login password.

PGADMIN_PW=secret

Environment Templates

Development Environment

# Application
TZ=UTC
PORT=3333
HOST=localhost
LOG_LEVEL=debug
DRIVE_DISK=fs
APP_KEY=generate-with-ace-command
NODE_ENV=development
SESSION_DRIVER=cookie

# Database (Docker)
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=root
DB_PASSWORD=root
DB_DATABASE=app

# Email (Mailpit)
SMTP_HOST=localhost
SMTP_PORT=1025
[email protected]
SMTP_PASSWORD=XXX
SMTP_SECURE=0
SMTP_REJECTUNAUTHORIZED=false
[email protected]

# OAuth
GOOGLE_CLIENT_ID=<your-key>
GOOGLE_CLIENT_SECRET=<your-key>

# Frontend
VITE_API_URL=http://localhost:3333

# Rate Limiting
LIMITER_STORE=database

# Docker Compose
COMPOSE_PROJECT_NAME=adonisjs
[email protected]
PGADMIN_PW=secret

Production Environment

# Application
TZ=UTC
PORT=3333
HOST=0.0.0.0
LOG_LEVEL=info
DRIVE_DISK=s3
APP_KEY=your-production-key-here
NODE_ENV=production
SESSION_DRIVER=redis

# Database
DB_HOST=your-db-host.com
DB_PORT=5432
DB_USER=production_user
DB_PASSWORD=strong-secure-password
DB_DATABASE=production_app

# Email (Resend)
RESEND_API_KEY=re_your_api_key
[email protected]

# OAuth
GOOGLE_CLIENT_ID=your-production-client-id
GOOGLE_CLIENT_SECRET=your-production-secret

# Frontend
VITE_API_URL=https://api.yourdomain.com

# Rate Limiting
LIMITER_STORE=redis

# S3 Storage
S3_KEY=your-access-key
S3_SECRET=your-secret-key
S3_BUCKET=your-bucket
S3_REGION=us-east-1

# Redis
REDIS_HOST=your-redis-host.com
REDIS_PORT=6379
REDIS_PASSWORD=redis-password

Security Best Practices

Never commit .env files

Add to .gitignore:

.env
.env.local
.env.production
.env.*.local

Use strong APP_KEY

Generate cryptographically secure keys:

node ace generate:key

Never reuse keys across environments.

Rotate credentials regularly

Change database passwords periodically
Rotate API keys every 90 days
Update OAuth secrets when compromised

Use secrets management in production

Consider using:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager
Railway/Render environment variables

Restrict access to .env files

chmod 600 .env

Only the application user should have read access.

Environment Validation

AdonisJS validates environment variables on startup. Missing required variables will cause the application to fail with clear error messages.

Manual Validation

Test your environment configuration:

# Check database connection
node ace db:check

# List all routes (validates app startup)
node ace list:routes

# Run migrations
node ace migration:run

Troubleshooting

APP_KEY is missing

Generate a new key:

node ace generate:key

Copy the output to your .env file:

APP_KEY=generated-key-here

Database connection fails

Verify PostgreSQL is running:
```
docker compose ps pgsql
```
Check credentials match .env
Test connection:
```
psql -h 127.0.0.1 -U root -d app
```

Environment variables not loading

Ensure .env file is in the correct directory (apps/web/)
Restart the application
Check file permissions:
```
ls -la apps/web/.env
```

Email sending fails

Verify SMTP settings:

# Test with Mailpit
curl http://localhost:8025

Check Mailpit is running:
```
docker compose ps mailpit
```
Review email logs in Mailpit UI

Next Steps

Docker Setup

Configure Docker for development

Production Deployment

Deploy to production servers

Getting Started

Project Structure

Core Features

Development

Deployment

Environment File

Getting Started

Core Configuration

Application Settings

Session Configuration

Database Configuration

PostgreSQL Settings

Connection String Alternative

Email Configuration

Resend (Recommended for Production)

SMTP (Development with Mailpit)

Email Configuration Examples

OAuth Configuration

Google OAuth

Storage Configuration

S3 Configuration (Optional)

Rate Limiting

Frontend Configuration

Docker Compose Variables

Project Configuration

PgAdmin Configuration

Environment Templates

Development Environment

Production Environment

Security Best Practices

Environment Validation

Manual Validation

Troubleshooting

Next Steps

Docker Setup

Production Deployment

Build docs developers (and LLMs) love

Getting Started

Project Structure

Core Features

Development

Deployment

​Environment File

​Getting Started

​Core Configuration

​Application Settings

​Session Configuration

​Database Configuration

​PostgreSQL Settings

​Connection String Alternative

​Email Configuration

​Resend (Recommended for Production)

​SMTP (Development with Mailpit)

​Email Configuration Examples

​OAuth Configuration

​Google OAuth

​Storage Configuration

​S3 Configuration (Optional)

​Rate Limiting

​Frontend Configuration

​Docker Compose Variables

​Project Configuration

​PgAdmin Configuration

​Environment Templates

​Development Environment

​Production Environment

​Security Best Practices

​Environment Validation

​Manual Validation

​Troubleshooting

​Next Steps

Docker Setup

Production Deployment

Build docs developers (and LLMs) love

Environment File

Getting Started

Core Configuration

Application Settings

Session Configuration

Database Configuration

PostgreSQL Settings

Connection String Alternative

Email Configuration

Resend (Recommended for Production)

SMTP (Development with Mailpit)

Email Configuration Examples

OAuth Configuration

Google OAuth

Storage Configuration

S3 Configuration (Optional)

Rate Limiting

Frontend Configuration

Docker Compose Variables

Project Configuration

PgAdmin Configuration

Environment Templates

Development Environment

Production Environment

Security Best Practices

Environment Validation

Manual Validation

Troubleshooting

Next Steps