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

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

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.

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

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

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

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.

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).

string

required

The name of your SMTP provider. Common values:

gmail
sendgrid
mailgun
custom

SMTP_PROVIDER=gmail

string

required

The email address or username for SMTP authentication.

SMTP_USER=contact@example.com

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.

string

required

The “From” email address used in outgoing emails.

SMTP_FROM=noreply@concordia.example.com

Optional SMTP Configuration

string

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

SMTP_HOST=smtp.gmail.com

number

default:"587"

SMTP server port. Common values:

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

SMTP_PORT=587

boolean

default:"false"

Whether to use SSL/TLS:

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

SMTP_SECURE=false

boolean

default:"true"

Whether to use connection pooling for better performance.

SMTP_POOL=true

number

default:"5"

Maximum number of simultaneous SMTP connections in the pool.

SMTP_MAX_CONNECTIONS=5

number

default:"1000"

Time window in milliseconds for rate limiting.

SMTP_RATE_DELTA=1000

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:

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

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

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

​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

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