Skip to main content

​
Overview

Walle uses environment variables for configuration across different deployment environments. All configuration is managed through a .env file in the project root, loaded by @nestjs/config in src/app.module.ts:12.

​
Required Environment Variables

​
PostgreSQL Configuration

PostgreSQL is used for storing telemetry points with table partitioning.
.env
# PostgreSQL Connection
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=ngynx
POSTGRES_PASSWORD=ngynx
POSTGRES_DB=walledb
POSTGRES_SYNC=false
​
POSTGRES_HOST
string
required
PostgreSQL server hostname or IP address. Use localhost for local development.
​
POSTGRES_PORT
number
default:"5432"
PostgreSQL server port. Default is 5432.
​
POSTGRES_USER
string
required
Database user with full privileges on the target database.
​
POSTGRES_PASSWORD
string
required
Password for the PostgreSQL user.
​
POSTGRES_DB
string
required
Target database name. Must have PostGIS extension enabled.
​
POSTGRES_SYNC
boolean
default:"false"
TypeORM synchronization setting. Must be false to allow manual partition management. Set in src/app/database/config/database-postgresql.config.ts:16.
Never set POSTGRES_SYNC=true in production. This can cause data loss when TypeORM attempts to synchronize the partitioned table structure.

​
MongoDB Configuration

Walle connects to two separate MongoDB databases for different purposes.
.env
# MongoDB Connections
MONGO_DELTA_DISPATCH_URI=mongodb://localhost:27017/deltaDispatch
MONGO_AUTHSOFTWARE_URI=mongodb://localhost:27017/authSoftware
​
MONGO_DELTA_DISPATCH_URI
string
required
MongoDB connection URI for the Delta Dispatch database. Used for dispatch-related data.Configured in src/app.module.ts:32 with connection name deltaDispatch.
​
MONGO_AUTHSOFTWARE_URI
string
required
MongoDB connection URI for the Auth Software database. Used for user authentication and management.Configured in src/app.module.ts:33 with connection name authSoftware.

​
Authentication Configuration

.env
# JWT Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
​
JWT_SECRET
string
required
Secret key for signing and verifying JWT tokens. Used in src/app/auth/strategies/jwt.strategy.ts:18.Security Requirements:
  • Minimum 32 characters
  • Use cryptographically secure random string
  • Never commit to version control
  • Rotate periodically in production
Generate a secure JWT secret:
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

​
Application Configuration

.env
# Application Settings
PORT=3700
NODE_ENV=development
​
PORT
number
default:"3700"
HTTP server port. The application listens on this port, configured in src/main.ts:17.
​
NODE_ENV
string
default:"development"
Application environment. Common values: development, production, staging.

​
Connection String Formats

​
PostgreSQL Connection String

While Walle uses individual environment variables for PostgreSQL, the equivalent connection string format is: 
postgresql://[user]:[password]@[host]:[port]/[database]
Example: 
postgresql://ngynx:ngynx@localhost:5432/walledb

​
MongoDB Connection Strings

mongodb://localhost:27017/deltaDispatch
mongodb://localhost:27017/authSoftware

​
Environment-Specific Configurations

​
Development Environment

.env.development
# PostgreSQL - Local
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=ngynx
POSTGRES_PASSWORD=ngynx
POSTGRES_DB=walledb
POSTGRES_SYNC=false

# MongoDB - Local
MONGO_DELTA_DISPATCH_URI=mongodb://localhost:27017/deltaDispatch
MONGO_AUTHSOFTWARE_URI=mongodb://localhost:27017/authSoftware

# Auth - Development secret
JWT_SECRET=dev-secret-key-not-for-production

# App
PORT=3700
NODE_ENV=development

​
Staging Environment

.env.staging
# PostgreSQL - Staging Server
POSTGRES_HOST=staging-db.example.com
POSTGRES_PORT=5432
POSTGRES_USER=walle_staging
POSTGRES_PASSWORD=${STAGING_DB_PASSWORD}
POSTGRES_DB=walledb_staging
POSTGRES_SYNC=false

# MongoDB - Atlas Staging Cluster
MONGO_DELTA_DISPATCH_URI=${STAGING_MONGO_DELTA_URI}
MONGO_AUTHSOFTWARE_URI=${STAGING_MONGO_AUTH_URI}

# Auth - Staging secret
JWT_SECRET=${STAGING_JWT_SECRET}

# App
PORT=3700
NODE_ENV=staging

​
Production Environment

.env.production
# PostgreSQL - Production RDS/Managed Instance
POSTGRES_HOST=prod-db.xxxxx.rds.amazonaws.com
POSTGRES_PORT=5432
POSTGRES_USER=walle_prod
POSTGRES_PASSWORD=${PROD_DB_PASSWORD}
POSTGRES_DB=walledb
POSTGRES_SYNC=false

# MongoDB - Atlas Production Cluster
MONGO_DELTA_DISPATCH_URI=${PROD_MONGO_DELTA_URI}
MONGO_AUTHSOFTWARE_URI=${PROD_MONGO_AUTH_URI}

# Auth - Production secret (rotate quarterly)
JWT_SECRET=${PROD_JWT_SECRET}

# App
PORT=3700
NODE_ENV=production
In production, use environment variable substitution (${VAR_NAME}) to inject secrets from your deployment platform (AWS Secrets Manager, Docker secrets, Kubernetes secrets, etc.).

​
Security Best Practices

Add .env to .gitignore to prevent committing secrets:
.gitignore
# Environment variables
.env
.env.local
.env.*.local
.env.production
Commit only example files:
.env.example
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
# ... (without actual values)
PostgreSQL:
  • Use strong passwords (minimum 16 characters)
  • Create dedicated database users with minimal privileges
  • Enable SSL/TLS for connections in production
MongoDB:
  • Enable authentication (--auth)
  • Use role-based access control (RBAC)
  • Enable encryption at rest and in transit
JWT:
  • Use minimum 256-bit secrets (32+ characters)
  • Rotate secrets periodically
  • Use different secrets per environment
PostgreSQL SSL:
POSTGRES_HOST=db.example.com
POSTGRES_SSL=true
POSTGRES_SSL_REJECT_UNAUTHORIZED=true
MongoDB TLS:
mongodb://user:pass@host:27017/db?ssl=true&tlsAllowInvalidCertificates=false
  • Use VPC/private networks for database access
  • Implement IP whitelisting on database servers
  • Enable firewall rules to restrict access
  • Use connection pooling with limits
  • Monitor and log all database connections
Development:
  • Use .env files locally
  • Never share .env files via chat/email
Production:
  • AWS: Use AWS Secrets Manager or Parameter Store
  • Docker: Use Docker secrets
  • Kubernetes: Use Kubernetes secrets or external secret managers
  • Azure: Use Azure Key Vault
  • GCP: Use Google Secret Manager
Example with AWS Secrets Manager:
# Store secret
aws secretsmanager create-secret \
  --name walle/prod/jwt-secret \
  --secret-string "your-secret-key"

# Retrieve in application
JWT_SECRET=$(aws secretsmanager get-secret-value \
  --secret-id walle/prod/jwt-secret \
  --query SecretString --output text)
Implement a rotation schedule:
  • JWT_SECRET: Every 90 days
  • Database passwords: Every 180 days
  • MongoDB credentials: Every 180 days
Use automated rotation where possible:
# AWS RDS automated password rotation
aws rds modify-db-instance \
  --db-instance-identifier walle-prod \
  --master-user-password $(generate-password) \
  --apply-immediately

​
Configuration Validation

​
Verify Configuration on Startup

Create a configuration validation service:
src/common/config/config.validation.ts
import { plainToClass } from 'class-transformer';
import { IsString, IsNumber, IsBoolean, validateSync } from 'class-validator';

class EnvironmentVariables {
  @IsString()
  POSTGRES_HOST: string;

  @IsNumber()
  POSTGRES_PORT: number;

  @IsString()
  POSTGRES_USER: string;

  @IsString()
  POSTGRES_PASSWORD: string;

  @IsString()
  POSTGRES_DB: string;

  @IsBoolean()
  POSTGRES_SYNC: boolean;

  @IsString()
  MONGO_DELTA_DISPATCH_URI: string;

  @IsString()
  MONGO_AUTHSOFTWARE_URI: string;

  @IsString()
  JWT_SECRET: string;

  @IsNumber()
  PORT: number;
}

export function validate(config: Record<string, unknown>) {
  const validatedConfig = plainToClass(EnvironmentVariables, config, {
    enableImplicitConversion: true,
  });
  
  const errors = validateSync(validatedConfig, {
    skipMissingProperties: false,
  });

  if (errors.length > 0) {
    throw new Error(errors.toString());
  }
  return validatedConfig;
}

​
Test Database Connections

Verify all connections are working: 
# PostgreSQL
psql -h $POSTGRES_HOST -p $POSTGRES_PORT -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT version();"

# MongoDB Delta Dispatch
mongosh "$MONGO_DELTA_DISPATCH_URI" --eval "db.adminCommand('ping')"

# MongoDB Auth Software
mongosh "$MONGO_AUTHSOFTWARE_URI" --eval "db.adminCommand('ping')"

​
Troubleshooting

Problem: Variables defined in .env are undefinedSolutions:
  • Ensure .env file is in project root (same directory as package.json)
  • Check file name is exactly .env (not .env.txt)
  • Verify ConfigModule.forRoot() includes correct envFilePath
  • Restart the application after changing .env
  • Use console.log(process.env.VARIABLE_NAME) to debug
Problem: ECONNREFUSED errorsSolutions:
  • Verify PostgreSQL is running: pg_isready -h $POSTGRES_HOST -p $POSTGRES_PORT
  • Check host and port values
  • Verify firewall allows connections on PostgreSQL port
  • For Docker: use host.docker.internal instead of localhost
Problem: MongoServerError: Authentication failedSolutions:
  • Verify username and password in connection URI
  • Check if authentication is enabled: mongosh --eval "db.adminCommand('getCmdLineOpts')"
  • Ensure user exists and has correct permissions
  • Verify database name in connection string
  • For Atlas: check network access IP whitelist
Problem: Security warnings about JWT secretSolutions:
  • Generate a strong secret using crypto: 
    node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
  • Ensure minimum 32 characters
  • Use different secrets for each environment

​
Next Steps

Partition Management

Learn how to manage database partitions

Setup Guide

Complete installation and setup process

Authentication

Configure JWT authentication

API Reference

Explore the API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us