Skip to content

CONFIG.md

Latest commit

 

History

History
287 lines (214 loc) · 8.32 KB

CONFIG.md

File metadata and controls

287 lines (214 loc) · 8.32 KB

Configuration Guide

This document describes all configuration options for ShadowCheckStatic.

Wiki references (diagrams): Deployment Guide, Installation

Configuration Files

File Purpose
.env Optional non-secret config only
.env.example Template (non-secret values)
.env.local Optional non-secret overrides
server/src/config/database.ts Database configuration
server/src/utils/serverConfig.ts Server configuration
config/servers.json Server definitions

Environment Variables

Database Configuration

Variable Required Default Description
DB_USER Yes - Database username
DB_ADMIN_USER Yes - Admin database username
DB_HOST Yes postgres Database host ('postgres' for Docker, 'localhost' for host-based)
DB_NAME Yes - Database name
DB_PORT No 5432 Database port
DB_PASSWORD Yes - Database password (see Secrets)

Server Configuration

Variable Required Default Description
PORT No 3001 Server port
NODE_ENV No development Environment mode
FORCE_HTTPS No false Force HTTPS redirect
CORS_ORIGINS No - Comma-separated CORS origins

Threat Detection

Variable Required Default Description
THREAT_THRESHOLD No 40 Minimum threat score threshold
MIN_OBSERVATIONS No 2 Minimum observations for analysis

Admin Controls

Variable Required Default Description
ADMIN_ALLOW_DOCKER No false Allow Docker controls in admin
PGADMIN_COMPOSE_FILE No - Path to pgAdmin compose file

Secrets Management

Secrets are loaded from AWS Secrets Manager at runtime. Secrets are never written to disk. Environment variables are allowed only as explicit, non-persistent overrides (e.g., local dev).

See SECRETS.md for the authoritative secrets guide.

Required Secrets

Secret Key Description
db_password Database password
db_admin_password Admin database password
mapbox_token Mapbox API token

Optional Secrets

Secret Key Description
api_key API authentication key
wigle_api_key WiGLE API key
wigle_api_token WiGLE API token
locationiq_api_key LocationIQ geocoding
opencage_api_key OpenCage geocoding
smarty_auth_id Smarty geocoding
smarty_auth_token Smarty geocoding
aws_region AWS region hint

Setting Secrets via Environment (Local Overrides Only)

export DB_PASSWORD=your_password
export MAPBOX_TOKEN=pk.your_token

Frontend Configuration

Frontend environment variables must be prefixed with VITE_:

Variable Description
VITE_MAPBOX_TOKEN Mapbox token for frontend
VITE_API_BASE API base URL
VITE_DEV_MODE Development mode flag

Place these in .env.local for local development.

Redis Configuration

Redis is optional but recommended for caching and rate limiting. Redis 7.0+ is the project standard for production deployments.

REDIS_HOST=localhost
REDIS_PORT=6379

If Redis is unavailable, the app degrades gracefully with caching disabled.

Mapbox Token

Set mapbox_token in AWS Secrets Manager. Use MAPBOX_TOKEN only for explicit local overrides.

Configuration in Development

Use environment variables for any secret overrides, and keep .env free of secrets.

  1. Export required values:

    export DB_PASSWORD=...
export DB_ADMIN_PASSWORD=...
export MAPBOX_TOKEN=...

  2. Start the development server:

    npm run dev

Configuration in Production

Secrets must be provisioned in AWS Secrets Manager. Do not store secrets in .env files.

Environment Variables in Docker

docker run \
  -e DB_HOST=shadowcheck_postgres \
  -e DB_USER=shadowcheck_user \
  -e DB_NAME=shadowcheck_db \
  -e PORT=3001 \
  shadowcheck/static:latest

Server Configuration

Database Configuration

File: server/src/config/database.ts

{
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432'),
  database: process.env.DB_NAME || 'shadowcheck_db',
  user: process.env.DB_USER,
  password: secrets.get('db_password'),
  max: 20, // Connection pool size
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
}

Server Configuration

File: server/src/utils/serverConfig.ts

{
  port: parseInt(process.env.PORT || '3001'),
  host: '0.0.0.0',
  env: process.env.NODE_ENV || 'development',
  corsOrigins: process.env.CORS_ORIGINS?.split(',') || [],
  forceHttps: process.env.FORCE_HTTPS === 'true',
}

Configuration Validation

The application validates configuration on startup:

// Required configurations
const required = ['DB_HOST', 'DB_NAME', 'DB_USER'];
required.forEach((key) => {
  if (!process.env[key]) {
    throw new Error(`Missing required config: ${key}`);
  }
});

Docker Compose Configuration

Development

# docker-compose.dev.yml
services:
  postgres:
    image: postgis/postgis:18-3.5
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    ports:
      - '5432:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data

  shadowcheck:
    build: .
    ports:
      - '3001:3001'
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
    depends_on:
      - postgres

Production

# docker-compose.yml
services:
  postgres:
    image: postgis/postgis:18-3.5
    volumes:
      - postgres_data:/var/lib/postgresql/data
    env_file:
      - .env.production

  shadowcheck:
    build: .
    ports:
      - '3001:3001'
    depends_on:
      - postgres
    secrets:
      - db_password
      - mapbox_token

Troubleshooting

Missing Configuration

Error: Missing required config: DB_HOST

Fix: Ensure required environment variables are set (non-secret values can be stored in .env if desired).

Database Connection Failed

Error: connect ECONNREFUSED 127.0.0.1:5432

Fix: Check that PostgreSQL is running and DB_HOST is correct.

Secret Not Found

Error: Secret not found: db_password

Fix: Ensure the secret exists in AWS Secrets Manager (env vars only for explicit local overrides).

Invalid Environment

Error: NODE_ENV must be 'production' or 'development'

Fix: Set NODE_ENV to a valid value.

Related Documentation