Configuration

Complete reference for all AsaHome Cloud configuration options.

Environment Variables

All configuration is done through environment variables. Copy env.example to .env and customize as needed.

Application Settings

Variable	Default	Description
NODE_ENV	development	Environment (development, production, test)
PORT	3000	Application port
API_PREFIX	api/v1	API route prefix

Database Configuration

Variable	Default	Description
DB_HOST	localhost	PostgreSQL host
DB_PORT	5432	PostgreSQL port
DB_USERNAME	postgres	Database user
DB_PASSWORD	postgres	Database password
DB_DATABASE	asahome_cloud	Database name
DB_SYNCHRONIZE	false	Auto-sync schema (disable in production)
DB_LOGGING	false	Enable SQL query logging

JWT Authentication

Variable	Default	Description
JWT_SECRET	-	Required. Secret key for signing tokens
JWT_EXPIRES_IN	15m	Access token lifetime
JWT_REFRESH_EXPIRES_IN	30d	Refresh token lifetime

Critical Security

The JWT_SECRET must be a strong, random string of at least 32 characters. Generate one with:

openssl rand -base64 32

CORS Configuration

Variable	Default	Description
CORS_ORIGINS	*	Allowed origins (comma-separated)
CORS_METHODS	GET,POST,PUT,DELETE,PATCH	Allowed HTTP methods
CORS_CREDENTIALS	true	Allow credentials

Rate Limiting

Variable	Default	Description
THROTTLE_TTL	60	Time window in seconds
THROTTLE_LIMIT	100	Max requests per window

Internal API Keys

Variable	Default	Description
INTERNAL_API_KEYS	-	Comma-separated API keys for service-to-service auth

# Example: Multiple internal API keys
INTERNAL_API_KEYS=key1-for-laravel,key2-for-other-service

WebSocket Configuration

Variable	Default	Description
WS_PORT	3001	WebSocket server port (if separate)
WS_PATH	/tunnel	WebSocket endpoint path

Example Configuration

Development

# .env.development
NODE_ENV=development
PORT=3000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=asahome_cloud_dev
DB_SYNCHRONIZE=true
DB_LOGGING=true

# JWT
JWT_SECRET=development-secret-change-in-production
JWT_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=7d

# CORS - Allow all in development
CORS_ORIGINS=*

# Rate Limiting - Relaxed for development
THROTTLE_TTL=60
THROTTLE_LIMIT=1000

Production

# .env.production
NODE_ENV=production
PORT=3000

# Database
DB_HOST=postgres
DB_PORT=5432
DB_USERNAME=asahome_user
DB_PASSWORD=<strong-password-here>
DB_DATABASE=asahome_cloud
DB_SYNCHRONIZE=false
DB_LOGGING=false

# JWT
JWT_SECRET=<generated-secret-here>
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=30d

# CORS - Restrict to known domains
CORS_ORIGINS=https://app.asahome.io,https://admin.asahome.io

# Rate Limiting
THROTTLE_TTL=60
THROTTLE_LIMIT=100

# Internal API Keys
INTERNAL_API_KEYS=<laravel-api-key>,<monitoring-api-key>

Docker Compose Configuration

The docker-compose.yml file orchestrates all services:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_DATABASE}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/ssl:/etc/nginx/ssl
    depends_on:
      - app

volumes:
  postgres_data:

Nginx Configuration

The default Nginx configuration handles:

• TLS Termination: SSL/HTTPS encryption
• WebSocket Proxying: Upgrade headers for Socket.IO
• Security Headers: HSTS, CSP, X-Frame-Options
• Rate Limiting: Per-IP request throttling

Key settings in nginx/conf.d/default.conf:

upstream backend {
    server app:3000;
}

server {
    listen 80;
    listen 443 ssl;
    
    # SSL Configuration
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
    
    # Security Headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    # API Proxy
    location /api {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    # WebSocket Proxy
    location /tunnel {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Validation

AsaHome Cloud validates configuration on startup. Missing required variables will cause the application to fail with a clear error message.

# Check current configuration (development only)
npm run config:validate

Next Steps

• Architecture Overview - Understand system components
• Authentication Guide - Learn about JWT configuration
• Deployment Guide - Production deployment steps