FJurmanovic/acc-server-manager
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
07407e4db170eb0fe19e00a960e31d3cba6d6614
acc-server-manager/documentation/CONFIGURATION.md
Fran Jurmanović caba5bae70 security improvements
2025-06-29 21:59:41 +02:00

9.7 KiB
Raw Blame History

Configuration Guide for ACC Server Manager

Overview

This guide provides comprehensive information about configuring the ACC Server Manager application, including environment variables, server settings, security configurations, and advanced options.

📁 Configuration Files

Environment Configuration (.env)

The primary configuration is handled through environment variables. Create a .env file in the root directory:

# Copy the example file
cp .env.example .env

Configuration File Hierarchy

  1. Environment Variables (highest priority)
  2. .env file (medium priority)
  3. Default values (lowest priority)

🔐 Security Configuration

Required Security Variables

These variables are mandatory and the application will not start without them:

# JWT Secret - Used for signing authentication tokens
# Generate with: openssl rand -base64 64
JWT_SECRET=your-super-secure-jwt-secret-minimum-64-characters-long

# Application Secrets - Used for internal encryption and security
# Generate with: openssl rand -hex 32
APP_SECRET=your-32-character-hex-secret-here
APP_SECRET_CODE=your-32-character-hex-secret-code-here

# Encryption Key - Used for AES-256 encryption (MUST be exactly 32 bytes)
# Generate with: openssl rand -hex 32
ENCRYPTION_KEY=your-exactly-32-byte-encryption-key-here

🌐 Server Configuration

Basic Server Settings

# HTTP server port
PORT=3000

# CORS allowed origin (comma-separated for multiple origins)
CORS_ALLOWED_ORIGIN=http://localhost:5173

# Database file name (SQLite)
DB_NAME=acc.db

# Default admin password for initial setup (change after first login)
PASSWORD=change-this-default-admin-password

Note: Most other server configuration options (timeouts, request limits, etc.) are handled by application defaults and don't require environment variables.

🗄️ Database Configuration

The application uses SQLite with minimal configuration required:

# Database file name (only setting available via environment)
DB_NAME=acc.db

Note: Other database settings like connection timeouts, migration settings, and SQL logging are handled internally by the application and don't require environment variables.

🎮 Steam Integration

Steam integration settings are managed through the web interface and stored in the database as system configuration. No environment variables are required for Steam integration.

Configuration via Web Interface:

  • SteamCMD executable path
  • NSSM executable path
  • Steam credentials (encrypted in database)
  • Update schedules and preferences

Default Values:

  • SteamCMD Path: c:\steamcmd\steamcmd.exe
  • NSSM Path: .\nssm.exe

🔥 Windows Service Configuration

Windows service and firewall configurations are handled internally by the application:

Service Management:

  • NSSM path configured via web interface
  • Default service name prefix: ACC-Server
  • Automatic service creation and management

Firewall Management:

  • Automatic firewall rule creation
  • Default TCP port range: 9600+
  • Default UDP port range: 9600+
  • Rule cleanup on server deletion

No environment variables required - all settings are managed through the system configuration interface.

📊 Logging Configuration

Logging is handled internally by the application with sensible defaults:

Default Logging Behavior:

  • Log level: info (adjustable via code)
  • Log format: Structured text format
  • Log files: Automatic rotation and cleanup
  • Security events: Automatically logged
  • Error tracking: Comprehensive error logging

No environment variables required - logging configuration is built into the application.

🚦 Rate Limiting Configuration

Rate limiting is built into the application with secure defaults:

Built-in Rate Limits:

  • Global: 100 requests per minute per IP
  • Authentication: 5 attempts per 15 minutes per IP
  • API endpoints: 60 requests per minute per IP
  • Configuration updates: Protected with additional limits

No environment variables required - rate limiting is automatically applied with appropriate limits for security and performance.

📈 Monitoring Configuration

Monitoring features are built into the application:

Available Monitoring:

  • Health check endpoint: /health (always enabled)
  • Performance tracking: Built-in performance monitoring
  • Error tracking: Automatic error logging and tracking
  • Security monitoring: Authentication and authorization events

No environment variables required - monitoring is automatically enabled with appropriate defaults.

🔄 Backup Configuration

Backup functionality is handled internally:

Automatic Backups:

  • Database backup before migrations
  • Configuration file versioning
  • Error recovery mechanisms

Manual Backups:

  • Database files can be copied manually
  • Configuration export/import via web interface

No environment variables required - backup features are built into the application workflow.

🧪 Development Configuration

Development Mode Settings

# Enable development mode (NEVER use in production)
DEV_MODE=false

# Enable debug endpoints
DEBUG_ENDPOINTS=false

# Enable hot reload (requires air)
HOT_RELOAD=false

# Disable security features for testing (DANGEROUS)
DISABLE_SECURITY=false

Testing Configuration

# Test database name
TEST_DB_NAME=acc_test.db

# Enable test fixtures
ENABLE_TEST_FIXTURES=false

# Test timeout in seconds
TEST_TIMEOUT=300

🏭 Production Configuration

Production Deployment Settings

# Production mode
PRODUCTION=true

# Enable HTTPS enforcement
FORCE_HTTPS=true

# Security-first configuration
SECURITY_STRICT=true

# Disable debug information
DISABLE_DEBUG_INFO=true

# Enable comprehensive monitoring
ENABLE_MONITORING=true

Performance Optimization

# Enable response compression
ENABLE_COMPRESSION=true

# Compression level (1-9)
COMPRESSION_LEVEL=6

# Enable response caching
ENABLE_CACHING=true

# Cache TTL in seconds
CACHE_TTL=300

# Maximum cache size in MB
CACHE_MAX_SIZE=100

🛠️ Advanced Configuration

Custom Port Ranges

# Custom TCP port ranges (comma-separated)
CUSTOM_TCP_PORTS=9600-9610,9700-9710

# Custom UDP port ranges (comma-separated)
CUSTOM_UDP_PORTS=9600-9610,9700-9710

# Exclude specific ports (comma-separated)
EXCLUDED_PORTS=9605,9705

Custom Paths

# Custom ACC server installation path
ACC_SERVER_PATH=C:\ACC_Server

# Custom configuration templates path
CONFIG_TEMPLATES_PATH=./templates

# Custom scripts path
SCRIPTS_PATH=./scripts

Integration Settings

# External API endpoints
EXTERNAL_API_ENABLED=false
EXTERNAL_API_URL=https://api.example.com
EXTERNAL_API_KEY=your-api-key-here

# Webhook notifications
WEBHOOK_ENABLED=false
WEBHOOK_URL=https://your-webhook-url.com
WEBHOOK_SECRET=your-webhook-secret

📋 Configuration Validation

Validation Rules

The application automatically validates configuration on startup:

  1. Required Variables: Must be present and non-empty
  2. Numeric Values: Must be valid numbers within acceptable ranges
  3. File Paths: Must be accessible and have appropriate permissions
  4. URLs: Must be valid URL format
  5. Encryption Keys: Must be exactly 32 bytes for AES-256

Configuration Errors

Common configuration errors and solutions:

"JWT_SECRET must be at least 32 bytes long"

  • Solution: Generate a longer JWT secret using openssl rand -base64 64

"ENCRYPTION_KEY must be exactly 32 bytes long"

  • Solution: Generate a 32-byte key using openssl rand -hex 32

"Invalid port number"

  • Solution: Ensure port numbers are between 1 and 65535

"SteamCMD not found"

  • Solution: Install SteamCMD and update the STEAMCMD_PATH variable

🔧 Configuration Management

Environment-Specific Configurations

Development (.env.development)

DEV_MODE=true
LOG_LEVEL=debug
CORS_ALLOWED_ORIGIN=http://localhost:3000

Production (.env.production)

PRODUCTION=true
FORCE_HTTPS=true
LOG_LEVEL=warn
SECURITY_STRICT=true

Testing (.env.test)

DB_NAME=acc_test.db
LOG_LEVEL=error
DISABLE_RATE_LIMITING=true

Configuration Templates

Create configuration templates for common setups:

Single Server Setup

# Minimal configuration for single server
PORT=3000
DB_NAME=acc.db
SERVICE_NAME_PREFIX=ACC-Server

Multi-Server Setup

# Configuration for multiple servers
AUTO_FIREWALL_RULES=true
PORT_RANGE_SIZE=20
SERVICE_START_TIMEOUT=120

High-Security Setup

# Maximum security configuration
FORCE_HTTPS=true
RATE_LIMIT_AUTH=3
SESSION_TIMEOUT=30
MAX_LOGIN_ATTEMPTS=3
LOCKOUT_DURATION=30
SECURITY_STRICT=true

🚨 Security Best Practices

Secret Management

  1. Never commit secrets to version control
  2. Use environment-specific secret files
  3. Rotate secrets regularly
  4. Use secure secret generation methods
  5. Limit access to configuration files

Production Security

  1. Enable HTTPS enforcement
  2. Configure appropriate CORS origins
  3. Set up proper rate limiting
  4. Enable comprehensive logging
  5. Regular security audits

📞 Configuration Support

Troubleshooting

For configuration issues:

  1. Check the application logs for specific error messages
  2. Validate environment variables using the built-in validation
  3. Refer to the examples in .env.example
  4. Test configuration changes in development first

Getting Help

  • Documentation: Check this guide and other documentation files
  • Issues: Report configuration bugs via GitHub Issues
  • Community: Ask questions in community discussions
  • Professional Support: Contact maintainers for enterprise support

Note: Always test configuration changes in a development environment before applying them to production.