Environment Variables

Concordia requires several environment variables for database connections, authentication, email, and API configuration.

Setup

Create a .env file in the root directory:

cp .env.example .env

Then configure the variables according to your environment.

Database Configuration

USE_DB_TEST

boolean

default:"false"

Controls which database to use during development:

true - Use test database (DATABASE_URL_TEST)
false - Use local or production database

USE_DB_TEST=true

USE_PROD_DB

boolean

default:"false"

Whether to connect to the production database:

true - Use production database (DATABASE_URL_PROD)
false - Use local or test database

USE_PROD_DB=false

Never set USE_PROD_DB=true in development unless you know what you’re doing.

DATABASE_URL_LOCAL

string

required

PostgreSQL connection string for local development database.Format:

postgresql://username:password@localhost:port/database_name

Example:

DATABASE_URL_LOCAL=postgresql://concordia:secret@localhost:5432/concordia_dev

DATABASE_URL_TEST

string

required

PostgreSQL connection string for test database used during automated testing.Format:

postgresql://username:password@localhost:port/database_name_test

Example:

DATABASE_URL_TEST=postgresql://concordia:secret@localhost:5432/concordia_test

DATABASE_URL_PROD

string

required

PostgreSQL connection string for production database.Format (Neon):

postgresql://username:password@host.neon.tech/database?sslmode=require&channel_binding=require

Example:

DATABASE_URL_PROD=postgresql://neondb_owner:abc123xyz@ep-cool-forest-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require

Always use SSL (sslmode=require) for production database connections.

Authentication Configuration

BETTER_AUTH_SECRET

string

required

Secret key used to sign JWT tokens and secure sessions. Must be a strong random string.Generation:

openssl rand -base64 32

Example:

BETTER_AUTH_SECRET=8TxJZ5K3m9qLp2Hn7YvR4wG6fU1sD0aB

Never commit this secret to version control. Generate a unique value for each environment.

BETTER_AUTH_URL

string

required

The base URL where your application is accessible. Used for generating callback URLs and verification links.Development:

BETTER_AUTH_URL=http://localhost:4321

Production:

BETTER_AUTH_URL=https://concordia.example.com

Do not include a trailing slash.

SMTP Email Configuration

Concordia uses SMTP for sending transactional emails (verification, password reset, notifications).

SMTP_PROVIDER

string

required

The name of your SMTP provider. Common values:

gmail
sendgrid
mailgun
custom

SMTP_PROVIDER=gmail

SMTP_USER

string

required

The email address or username for SMTP authentication.

SMTP_USER=contact@example.com

SMTP_PASS

string

required

The password or app-specific password for SMTP authentication.

SMTP_PASS=your_password_here

For Gmail, use an App Password instead of your account password.

SMTP_FROM

string

required

The “From” email address used in outgoing emails.

SMTP_FROM=noreply@concordia.example.com

Optional SMTP Configuration

SMTP_HOST

string

Custom SMTP server hostname. If not set, automatically determined from SMTP_PROVIDER.

SMTP_HOST=smtp.gmail.com

SMTP_PORT

number

default:"587"

SMTP server port. Common values:

587 - TLS (recommended)
465 - SSL
25 - Unencrypted (not recommended)

SMTP_PORT=587

SMTP_SECURE

boolean

default:"false"

Whether to use SSL/TLS:

true - Use SSL (port 465)
false - Use STARTTLS (port 587)

SMTP_SECURE=false

SMTP_POOL

boolean

default:"true"

Whether to use connection pooling for better performance.

SMTP_POOL=true

SMTP_MAX_CONNECTIONS

number

default:"5"

Maximum number of simultaneous SMTP connections in the pool.

SMTP_MAX_CONNECTIONS=5

SMTP_RATE_DELTA

number

default:"1000"

Time window in milliseconds for rate limiting.

SMTP_RATE_DELTA=1000

SMTP_RATE_LIMIT

number

default:"5"

Maximum number of emails to send within the rate limit window.

SMTP_RATE_LIMIT=5

Alternative Email Provider: Resend

As an alternative to SMTP, you can use Resend for email delivery:

RESEND_API_KEY

string

API key from your Resend account. When set, Resend will be used instead of SMTP.

RESEND_API_KEY=re_123456789abcdefghijklmnop

To use Resend, comment out or remove SMTP variables and set only RESEND_API_KEY.

Application Configuration

NODE_ENV

string

default:"development"

The environment mode for Node.js. Affects logging, error handling, and optimizations.Valid values:

development - Development mode with verbose logging
production - Production mode with optimizations
test - Test mode for automated testing

NODE_ENV=development

PUBLIC_API_URL

string

Public-facing API URL used by client-side code. Must be accessible from the browser.Development:

PUBLIC_API_URL=http://localhost:4321/api

Production:

PUBLIC_API_URL=https://concordia.example.com/api

Variables prefixed with PUBLIC_ are exposed to client-side code. Never put secrets in PUBLIC_ variables.

Complete Example Configuration

Here’s a complete .env file template with all variables:

.env

# Database Selection
USE_DB_TEST=true
USE_PROD_DB=false

# Database URLs
DATABASE_URL_LOCAL=postgresql://concordia:dev_password@localhost:5432/concordia_dev
DATABASE_URL_TEST=postgresql://concordia:test_password@localhost:5432/concordia_test
DATABASE_URL_PROD=postgresql://user:pass@host.neon.tech/db?sslmode=require&channel_binding=require

# Authentication
BETTER_AUTH_SECRET=8TxJZ5K3m9qLp2Hn7YvR4wG6fU1sD0aB
BETTER_AUTH_URL=http://localhost:4321

# SMTP Configuration (Primary)
SMTP_PROVIDER=gmail
SMTP_USER=contact@example.com
SMTP_PASS=your_app_password
SMTP_FROM=noreply@example.com

# Optional: SMTP Overrides
# SMTP_HOST=smtp.gmail.com
# SMTP_PORT=587
# SMTP_SECURE=false
# SMTP_POOL=true
# SMTP_MAX_CONNECTIONS=5
# SMTP_RATE_DELTA=1000
# SMTP_RATE_LIMIT=5

# Alternative: Resend API (Comment out SMTP if using this)
# RESEND_API_KEY=re_123456789abcdefghijklmnop

# Application
NODE_ENV=development
PUBLIC_API_URL=http://localhost:4321/api

Testing Your Configuration

Test Database Connection

npm run db:check

Test SMTP Configuration

npm run smtp:check

This will attempt to send a test email and report any configuration issues.

Environment-Specific Files

Development
Production
Testing

Create .env.development:

USE_DB_TEST=true
USE_PROD_DB=false
DATABASE_URL_LOCAL=postgresql://localhost:5432/concordia_dev
BETTER_AUTH_URL=http://localhost:4321
NODE_ENV=development
PUBLIC_API_URL=http://localhost:4321/api

Create .env.production:

USE_DB_TEST=false
USE_PROD_DB=true
DATABASE_URL_PROD=postgresql://[secure-connection-string]
BETTER_AUTH_SECRET=[generate-new-secret]
BETTER_AUTH_URL=https://concordia.example.com
NODE_ENV=production
PUBLIC_API_URL=https://concordia.example.com/api

Never commit production .env files to version control. Use your hosting platform’s environment variable management.

Create .env.test:

USE_DB_TEST=true
USE_PROD_DB=false
DATABASE_URL_TEST=postgresql://localhost:5432/concordia_test
BETTER_AUTH_SECRET=test-secret-key
BETTER_AUTH_URL=http://localhost:4321
NODE_ENV=test
PUBLIC_API_URL=http://localhost:4321/api

Security Best Practices

Never Commit Secrets

Add .env* to your .gitignore:

.gitignore

.env
.env.local
.env.production
.env.development
.env.test

Generate Strong Secrets

Use cryptographically secure random values:

# Generate BETTER_AUTH_SECRET
openssl rand -base64 32

# Generate alternative secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Use Different Secrets Per Environment

Never reuse the same BETTER_AUTH_SECRET across development, staging, and production.

Rotate Secrets Regularly

Change authentication secrets and API keys periodically, especially after:

Team member departures
Security incidents
Suspected compromise

Limit Database Permissions

Use database users with minimal required permissions:

Development: Full access to dev database only
Production: No DDL permissions, only DML (SELECT, INSERT, UPDATE, DELETE)

Troubleshooting

Database Connection Failed

Error: Error: connect ECONNREFUSEDSolutions:

Ensure PostgreSQL is running:
```
sudo service postgresql status
```
Check connection string format
Verify username, password, and database name
Test with npm run db:check

SMTP Authentication Failed

Error: Invalid login: 535-5.7.8 Username and Password not acceptedSolutions:

For Gmail: Use an App Password, not your account password
Check SMTP_USER and SMTP_PASS are correct
Verify SMTP provider settings
Test with npm run smtp:check

JWT Token Invalid

Error: JsonWebTokenError: invalid signatureSolutions:

Ensure BETTER_AUTH_SECRET is set and matches between environments
Check for whitespace or newlines in the secret
Regenerate the secret if corrupted

Environment Variables Not Loading

Issue: Variables are undefined at runtimeSolutions:

Ensure .env file is in the project root
Restart the development server after changing .env
Check for typos in variable names
Verify dotenv is configured in astro.config.mjs

Next Steps

Database Setup

Learn about the database schema and migrations

Authentication

Configure authentication and user management

Setup

Production

Documentation Index

​Setup

​Database Configuration

​Authentication Configuration

​SMTP Email Configuration

​Optional SMTP Configuration

​Alternative Email Provider: Resend

​Application Configuration

​Complete Example Configuration

​Testing Your Configuration

​Test Database Connection

​Test SMTP Configuration

​Environment-Specific Files

​Security Best Practices

​Troubleshooting

​Next Steps

Database Setup

Authentication

Build docs developers (and LLMs) love

Setup

Database Configuration

Authentication Configuration

SMTP Email Configuration

Optional SMTP Configuration

Alternative Email Provider: Resend

Application Configuration

Complete Example Configuration

Testing Your Configuration

Test Database Connection

Test SMTP Configuration

Environment-Specific Files

Security Best Practices

Troubleshooting

Next Steps