Skip to content

CONFIGURATION.md

Latest commit

 

History

History
342 lines (263 loc) · 7.9 KB

CONFIGURATION.md

File metadata and controls

342 lines (263 loc) · 7.9 KB
Raw

TEX Platform Configuration

This document describes the global configuration system for the TEX Platform, which provides a flexible, provider-based architecture for managing various services and features.

Overview

The configuration system uses a single JSON configuration file to manage all application settings. The path to this file can be specified via the TEX_CONFIG_PATH environment variable. By default, it looks for ./config.json in the project root.

Architecture

Core Components

  1. Configuration Types (types/config.ts) - TypeScript interfaces for all configuration options
  2. Configuration Manager (config/manager.ts) - Handles loading and validation, of configuration
  3. Service Manager (config/services.ts) - Manages service lifecycle
  4. Configuration CLI (scripts/config.ts) - Command-line tool for configuration management; start with bun run config:help

Supported Providers

File Storage (Filer)

  • BunFS - Local filesystem storage using Bun
  • S3 - Amazon S3 or S3-compatible storage

Email

  • Console - Development email logging to console
  • SMTP - Standard SMTP email sending

Database

  • PostgreSQL - Primary database

Configuration Structure

The configuration is organized into several main sections:

{
  "app": {
    "name": "TEX Platform API",
    "version": "1.0.0",
    "environment": "development",
    "port": 3000
  },
  "database": { /* Database configuration */ },
  "security": { /* Security settings */ },
  "monitoring": { /* Logging and monitoring */ },
  "providers": {
    "filer": { /* File storage provider */ },
    "email": { /* Email provider */ },
    "auth": { /* Auth provider */ }    
  },
}

Configuration

Setting the Configuration File Path

The application looks for the TEX_CONFIG_PATH environment variable to determine which JSON configuration file to load. If not set, it defaults to ./config.json.

# Use default config.json in current directory
bun run start

# Use a specific configuration file
export TEX_CONFIG_PATH=./config.production.json
bun run start

# Or inline
TEX_CONFIG_PATH=./config.staging.json bun run start

JSON Configuration File

The specified config file can be intiated with default values using the CLI:

# Initialize default configuration
bun run config:init

Edit the JSON file directly to configure all aspects of the application. CLI commands can be used to get/set values without editing the file directly:

# Show current configuration
bun run config show

# Validate configuration
bun run config validate

# Test service connections
bun run config test

# Set configuration values
bun run config set app.port 8080
bun run config set providers.filer.basePath ./new-uploads

# Get configuration values
bun run config get providers.email.type

# Backup and restore
bun run config backup config.backup.json
bun run config restore config.backup.json

Provider Configuration Examples

File Storage Providers

BunFS (Local Filesystem)

{
  "type": "bunfs",
  "enabled": true,
  "basePath": "./uploads",
  "maxFileSize": 104857600,
  "allowedMimeTypes": ["image/*", "application/pdf"]
}

Amazon S3

{
  "type": "s3",
  "enabled": true,
  "accessKeyId": "${AWS_ACCESS_KEY_ID}",
  "secretAccessKey": "${AWS_SECRET_ACCESS_KEY}",
  "region": "us-east-1",
  "bucket": "my-tex-platform-files"
}

Email Providers

SMTP

{
  "type": "smtp",
  "enabled": true,
  "host": "smtp.gmail.com",
  "port": 587,
  "secure": false,
  "auth": {
    "user": "your-email@gmail.com",
    "pass": "your-app-password"
  },
  "from": "noreply@tex-platform.com"
}

Environment-Specific Configuration

Create different configuration files for different environments:

  • config.json - Default/development
  • config.production.json - Production
  • config.staging.json - Staging
  • config.test.json - Testing

Load specific configurations by setting the TEX_CONFIG_PATH environment variable:

# Development (default)
bun run dev

# Production
TEX_CONFIG_PATH=./config.production.json bun run start

# Staging
TEX_CONFIG_PATH=./config.staging.json bun run start

# Testing
TEX_CONFIG_PATH=./config.test.json bun run test

Security Considerations

Keep configuration files out of version control for sensitive deployments. Use .gitignore:

config.production.json
config.*.local.json

You can also use environment variables for sensitive values and reference them in the configuration file using ${ENV_VAR_NAME} syntax.

The system validates configuration on startup. When exporting config using bun run config show, sensitive fields (passwords, secrets, API keys) are redacted by default to prevent accidental exposure. Use --no-sanitize to view full values when needed (keep secure).

Monitoring and Health Checks

The system provides built-in health checking:

# Test all services
bun run config test

# Check health endpoint
curl http://localhost:3000/health

Health check response:

{
  "status": "healthy",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "services": {
    "filer": true,
    "email": true,
    "auth": true,
    "database": true
  },
  "version": "1.0.0"
}

Development Workflow

  1. Initial Setup:

    # Initialize default configuration
bun run config:init

  2. Configure Services (edit config.json):

    {
  "database": {
    "host": "localhost",
    "port": 5432,
    "database": "tex",
    "username": "tex_user",
    "password": "tex_password"
  },
  "providers": {
    "filer": {
      "type": "bunfs",
      "basePath": "./dev-uploads"
    },
    "email": {
      "type": "mock"
    }
  }
}

  3. Validate and Test:

    bun run config:validate
bun run config:test

  4. Start Application:

    bun run dev

Production Deployment

  1. Create Production Configuration:

    # Start with example
cp config.json config.production.json

  2. Edit Configuration File:

    • Set app.environment to "production"
    • Configure database with production credentials
    • Set up email provider
    • Configure file storage
    • Update security settings (CORS origins, etc.)

  3. Validate Configuration:

    TEX_CONFIG_PATH=./config.production.json bun run config:validate

  4. Test Service Connections:

    TEX_CONFIG_PATH=./config.production.json bun run config:test

  5. Deploy:

    # Set the configuration path
export TEX_CONFIG_PATH=./config.production.json

# Start application
bun run start

Troubleshooting

Common Issues

  1. Configuration Not Loading:

    • Check that the TEX_CONFIG_PATH environment variable is set correctly
    • Verify JSON syntax in the configuration file
    • Check file permissions for the configuration file
    • Ensure the file exists at the specified path

  2. Service Connection Failures:

    # Test all services
bun run config:test

# Check health endpoint
curl http://localhost:3000/health

  3. Invalid Configuration:

    # Validate configuration
bun run config:validate

Configuration Export

Export current configuration for debugging:

# Sanitized (safe to share)
bun run config show

# With sensitive data (keep secure)
bun run config show --no-sanitize

API Integration

Access services in your application code:

import { getServiceManager } from './config/services';

// Get initialized services
const serviceManager = getServiceManager();
const services = await serviceManager.initialize();

// Use providers
const fileId = await services.filer.uploadFile(file);
await services.email.sendEmail(to, subject, body);
const token = await services.auth.generateAuthToken(userId);

This configuration system can be extended to support additional providers as needed.