Configuration System

This guide covers the configuration management system for IRC.atl.chat, including template processing, environment variables, and automated configuration generation.

Overview

Configuration Architecture

IRC.atl.chat uses a template-based configuration system:

Configuration Flow:
├── env.example          - Template with defaults
├── .env                 - User configuration
├── *.template           - Configuration templates
├── envsubst             - Variable substitution
└── *.conf               - Generated configurations

Key Principles

Template-driven: All configuration from templates
Environment-based: Variables from .env file
Automated generation: No manual config editing
Version control safe: Templates committed, configs ignored
Validation: Automated config checking

Environment Configuration

.env File Structure

The .env file is the central configuration point:

# =============================================================================
# IRC.atl.chat Environment Configuration
# =============================================================================

# Core system settings
UNREALIRCD_VERSION=6.2.0.1
PUID=1000
PGID=1000
TZ=UTC

# Network identity
IRC_DOMAIN=irc.atl.chat
IRC_ROOT_DOMAIN=atl.chat
IRC_NETWORK_NAME=atl.chat

# Security settings
IRC_OPER_PASSWORD='$argon2id$...'
LETSENCRYPT_EMAIL=admin@atl.chat

# Service configuration
ATHEME_SEND_PASSWORD=secure_password_here
WEBPANEL_RPC_PASSWORD=admin_password

Environment Variable Categories

System Configuration

# Container user/group IDs (match host user)
PUID=1000                    # Host user ID
PGID=1000                    # Host group ID
TZ=UTC                       # System timezone

# Software versions
UNREALIRCD_VERSION=6.2.0.1   # IRC server version

Network Configuration

# Domain and network identity
IRC_DOMAIN=irc.atl.chat           # Server hostname
IRC_ROOT_DOMAIN=atl.chat          # Base domain
IRC_NETWORK_NAME=atl.chat         # Network name

# Port configuration
IRC_TLS_PORT=6697                # IRC over TLS
IRC_SERVER_PORT=6900             # Server linking
IRC_RPC_PORT=8600                # JSON-RPC API
IRC_WEBSOCKET_PORT=8000          # WebSocket IRC

Security Configuration

# Authentication
IRC_OPER_PASSWORD='$argon2id$...'  # IRC operator password
LETSENCRYPT_EMAIL=admin@domain.com # SSL certificate email

# Service passwords
ATHEME_SEND_PASSWORD=password     # Atheme-IRCd communication
ATHEME_RECEIVE_PASSWORD=password  # Atheme-IRCd communication
IRC_SERVICES_PASSWORD=password    # Services password

Environment File Management

Creating .env File

# Copy template
cp env.example .env

# Edit with your values
vim .env

# Secure permissions
chmod 600 .env

Environment Validation

# Validate .env syntax
bash -n .env

# Test variable substitution
env | grep IRC_

Template System

Template Processing

Template Files

Configuration templates use environment variable substitution:

# Template syntax
${VARIABLE_NAME}
${VARIABLE_NAME:-default_value}

# Generated output
actual_value
default_value (if VARIABLE_NAME not set)

Processing Pipeline

# 1. Read template
cat unrealircd.conf.template

# 2. Substitute variables
envsubst < unrealircd.conf.template > unrealircd.conf

# 3. Set permissions
chmod 644 unrealircd.conf

Template Locations

UnrealIRCd Templates

src/backend/unrealircd/conf/
├── unrealircd.conf.template     # Main server config
├── modules.default.conf         # Core modules
├── modules.custom.conf          # Custom modules
├── operclass.default.conf       # Operator classes
└── aliases/atheme.conf          # Service aliases

Atheme Templates

src/backend/atheme/conf/
└── atheme.conf.template         # Services configuration

Template Examples

UnrealIRCd Main Config

me {
    name "${IRC_DOMAIN}";
    info "${IRC_NETWORK_NAME} IRC Server";
};

admin {
    "${IRC_ADMIN_NAME}";
    "admin";
    "${IRC_ADMIN_EMAIL}";
};

listen {
    ip *;
    port ${IRC_TLS_PORT};
    options { tls; };
};

Atheme Services Config

serverinfo {
    name = "${ATHEME_SERVER_NAME}";
    uplink = "127.0.0.1";
    recontime = ${ATHEME_RECONTIME};
};

uplink {
    send_password = "${ATHEME_SEND_PASSWORD}";
    receive_password = "${ATHEME_RECEIVE_PASSWORD}";
    port = ${ATHEME_UPLINK_PORT};
};

Configuration Generation

Automated Processing

Build-time Generation

# Triggered by make up
# Configuration is processed automatically during container build

# What happens:
# 1. Templates are processed with envsubst
# 2. Generated .conf files are created
# 3. Proper permissions are set

Manual Generation

# Process specific template
export IRC_DOMAIN=irc.example.com
envsubst < template.conf > generated.conf

Generated Files

Gitignore Pattern

Generated configurations are automatically ignored:

# Generated configurations
src/backend/*/conf/*.conf
!src/backend/*/conf/*.template
!src/backend/*/conf/modules.*.conf
!src/backend/*/conf/operclass.*.conf

File Permissions

# Configuration files
-rw-r--r--  644 *.conf

# Credential files
-rw-------  600 .env
-rw-------  600 cloudflare-credentials.ini

Validation and Testing

Configuration Validation

Syntax Checking

# UnrealIRCd config validation
unrealircd -c /path/to/unrealircd.conf

# Atheme config validation
atheme-services -c /path/to/atheme.conf

Environment Validation

# Test environment setup
make test-env

# Check variable formats manually
grep -E "^[A-Z_]+=" .env

Testing Configurations

Dry Run Testing

# Test UnrealIRCd config
docker run --rm -v $(pwd)/src/backend/unrealircd/conf:/conf \
    unrealircd unrealircd -c /conf/unrealircd.conf -t

# Test Atheme config
docker run --rm -v $(pwd)/src/backend/atheme/conf:/conf \
    atheme atheme-services -c /conf/atheme.conf -n

Runtime Testing

# Start with test config
make test-env

# Validate service startup
make test-irc

Security Considerations

Secret Management

Password Storage

# Hashed passwords (IRC operators)
IRC_OPER_PASSWORD='$argon2id$v=19$m=6144,t=2,p=2$salt$hash'

# Service passwords (plaintext for communication)
ATHEME_SEND_PASSWORD=secure_random_string

File Permissions

# Environment file (owner read/write only)
chmod 600 .env

# Generated configs (world readable)
chmod 644 *.conf

# SSL certificates (readable by services)
chmod 644 server.cert.pem
chmod 644 server.key.pem

Access Control

Configuration Access

.env file contains sensitive data
Templates are safe for version control
Generated configs are runtime-only

Audit Logging

# Log configuration changes
echo "$(date): Config regenerated by $(whoami)" >> config-audit.log

# Track template modifications
git log --oneline src/backend/*/conf/*.template

Configuration Management

Environment Setup

# Copy template to create your configuration
cp env.example .env

# Edit with your values
vim .env

# Secure the file
chmod 600 .env

Advanced Configuration

Dynamic Configuration

Runtime Configuration Changes

# Modify .env
vim .env

# Regenerate configs
make build

# Restart services
make restart

Configuration Reloading

Some configuration changes require service restart:

# Restart services to apply changes
make restart

Template Extensions

Custom Templates

# Create custom template
cp unrealircd.conf.template custom.conf.template

# Add custom variables
echo 'custom_setting = "${CUSTOM_VAR}"' >> custom.conf.template

# Generate custom config
envsubst < custom.conf.template > custom.conf

Template Includes

// Include additional config files
include "custom.conf";
include "modules.custom.conf";

Configuration Overrides

Environment Overrides

# Override at runtime
IRC_DOMAIN=dev.irc.atl.chat make up

# Temporary overrides
export IRC_TLS_PORT=6698
make up

Service-Specific Configs

# Docker Compose overrides
environment:
  - IRC_DOMAIN=staging.irc.atl.chat
  - IRC_TLS_PORT=6698

Troubleshooting

Common Configuration Issues

Template Processing Errors

# Missing variables
envsubst < template.conf
# Error: bad substitution

# Check required variables
echo ${REQUIRED_VAR:?"Variable not set"}

# Validate .env file
bash -n .env

Permission Errors

# File permission issues
ls -la .env
# Should be: -rw------- owner

# Fix permissions
chmod 600 .env

# Check user alignment
echo "PUID: $(id -u), PGID: $(id -g)"

Configuration Syntax Errors

# UnrealIRCd syntax check
unrealircd -c unrealircd.conf 2>&1 | head -20

# Atheme syntax check
atheme-services -c atheme.conf -n

# Common errors:
# - Missing semicolons
# - Unclosed braces
# - Invalid variable names

Variable Substitution Issues

# Debug variable values
env | grep IRC_

# Test substitution
echo "Domain: ${IRC_DOMAIN}"
echo "Port: ${IRC_TLS_PORT:-6697}"

# Check for special characters
grep -n '[^a-zA-Z0-9_]' .env

Debug Procedures

Enable Debug Logging

# Add debug variables
DEBUG=1
VERBOSE=1

# Run with debug output
make up

# Check logs for config processing
make logs | grep -i config

Configuration Validation

# Validate all generated configs
find src/backend -name "*.conf" -exec echo "Checking {}" \; \
    -exec unrealircd -c {} -t \; 2>/dev/null || echo "Invalid: {}"

Recovery Procedures

# Restore from backup
cp backup/.env .env
cp backup/*.template src/backend/*/conf/

# Regenerate configurations
make build

# Test configuration
make test-env

Backup and Recovery

Configuration Backups

Automated Backups

# Backup .env file
cp .env backup/env-$(date +%Y%m%d).backup

# Backup templates
tar czf backup/templates-$(date +%Y%m%d).tar.gz \
    src/backend/*/conf/*.template

Version Control

# Templates are version controlled
git add src/backend/*/conf/*.template
git commit -m "Update configuration templates"

# .env is ignored (contains secrets)
echo ".env" >> .gitignore

Recovery Procedures

Configuration Recovery

# Restore .env
cp backup/env-latest.backup .env

# Restore templates
tar xzf backup/templates-latest.tar.gz

# Regenerate configs
make build

# Test recovery
make test-env

Emergency Config Generation

# Generate minimal config for testing
export IRC_DOMAIN=localhost
export IRC_TLS_PORT=6697
export IRC_ADMIN_NAME="Emergency Admin"

# Create basic .env
cat > .env << EOF
IRC_DOMAIN=localhost
IRC_TLS_PORT=6697
IRC_ADMIN_NAME=Emergency Admin
IRC_ADMIN_EMAIL=admin@localhost
EOF

# Regenerate configs
make build

Maintenance

Regular Tasks

Configuration Audits

# Check for outdated templates
find src/backend -name "*.template" -newer *.conf

# Validate all configurations
make test-env

# Review .env for security
grep -E "(PASSWORD|SECRET)" .env

Template Updates

# Update templates from upstream
git pull origin main

# Check for template changes
git diff src/backend/*/conf/*.template

# Test new templates
make build
make test

Documentation Updates

Configuration Documentation

# Update env.example comments
vim env.example

# Document new variables
echo "# NEW_VAR - Description" >> env.example

# Update this documentation
vim docs/CONFIG.md

FilesExpand file tree

CONFIG.md

Latest commit

History

CONFIG.md

File metadata and controls

Configuration System

Overview

Configuration Architecture

Key Principles

Environment Configuration

.env File Structure

Environment Variable Categories

System Configuration

Network Configuration

Security Configuration

Environment File Management

Creating .env File

Environment Validation

Template System

Template Processing

Template Files

Processing Pipeline

Template Locations

UnrealIRCd Templates

Atheme Templates

Template Examples

UnrealIRCd Main Config

Atheme Services Config

Configuration Generation

Automated Processing

Build-time Generation

Manual Generation

Generated Files

Gitignore Pattern

File Permissions

Validation and Testing

Configuration Validation

Syntax Checking

Environment Validation

Testing Configurations

Dry Run Testing

Runtime Testing

Security Considerations

Secret Management

Password Storage

File Permissions

Access Control

Configuration Access

Audit Logging

Configuration Management

Environment Setup

Advanced Configuration

Dynamic Configuration

Runtime Configuration Changes

Configuration Reloading

Template Extensions

Custom Templates

Template Includes

Configuration Overrides

Environment Overrides

Service-Specific Configs

Troubleshooting

Common Configuration Issues

Template Processing Errors

Permission Errors

Configuration Syntax Errors

Variable Substitution Issues

Debug Procedures

Enable Debug Logging

Configuration Validation

Recovery Procedures

Backup and Recovery

Configuration Backups

Automated Backups

Version Control

Recovery Procedures

Configuration Recovery

Emergency Config Generation

Maintenance