debian-forge/config/README.md

Debian Forge Configuration

This directory contains configuration files for Debian Forge. The system is designed to be collaborative-friendly, allowing each developer to have their own settings without affecting others.

Configuration Files

debian-forge.conf (Default Configuration)

• Purpose: Default configuration values for the project
• Status: Tracked in git (shared by all collaborators)
• Usage: Contains sensible defaults and examples

debian-forge.local.conf.example (Template)

• Purpose: Template for local configuration
• Status: Tracked in git (shared template)
• Usage: Copy this file to create your local configuration

debian-forge.local.conf (Local Configuration)

• Purpose: Your personal configuration settings
• Status: NOT tracked in git (personal to each collaborator)
• Usage: Customize this file for your environment

Quick Start

1. Set up your local configuration

# Create your local configuration file
./tools/debian-forge-config setup

# This copies the example template to config/debian-forge.local.conf
# Edit this file to customize your settings

2. Configure apt-cacher-ng proxy

# Set your proxy URL
./tools/debian-forge-config apt-proxy http://localhost:3142

# Or disable proxy
./tools/debian-forge-config apt-proxy none

# Or set via environment variable
export DEBIAN_FORGE_APT_PROXY=http://localhost:3142

3. View current configuration

./tools/debian-forge-config show

Configuration Options

apt-cacher-ng Section

[apt-cacher-ng]
# Set to your proxy URL, or leave empty to disable
url = http://localhost:3142

Examples:

• url = http://localhost:3142 - Local proxy
• url = http://192.168.1.100:3142 - Network proxy
• url = http://apt-cache.company.local:3142 - Company proxy
• url = - No proxy (leave empty)

build Section

[build]
# We support Debian 13+ (Trixie and newer)
# Current Debian releases:
# - trixie (Debian 13) - STABLE (recommended)
# - forky (Debian 14) - TESTING
# - sid (Debian Unstable) - UNSTABLE (use with caution)
default_suite = trixie
default_arch = amd64
timeout = 3600
jobs = 4

Debian Release Status (as of 2024):

• trixie (Debian 13) - STABLE - Recommended for production
• forky (Debian 14) - TESTING - For development and testing
• sid (Debian Unstable) - UNSTABLE - Use with caution
• bookworm (Debian 12) - OLDSTABLE - Limited support
• bullseye (Debian 11) - OLDOLDSTABLE - Not supported

Note: Debian Forge supports Debian 13+ (Trixie and newer). Older releases may have compatibility issues.

stages Section

[stages]
apt_update = true
apt_recommends = false
apt_unauthenticated = false

Priority Order

Configuration values are loaded in this priority order (highest to lowest):

1. Stage options (passed directly to stages)
2. Environment variables (e.g., DEBIAN_FORGE_APT_PROXY)
3. Local configuration (debian-forge.local.conf)
4. Default configuration (debian-forge.conf)

Environment Variables

You can override any configuration setting using environment variables:

# Override apt-cacher-ng proxy
export DEBIAN_FORGE_APT_PROXY=http://localhost:3142

# Override default suite
export DEBIAN_FORGE_DEFAULT_SUITE=forky

# Override default architecture
export DEBIAN_FORGE_DEFAULT_ARCH=arm64

CLI Tool Usage

The debian-forge-config tool provides several commands:

# Set up local configuration
./tools/debian-forge-config setup

# Show current configuration
./tools/debian-forge-config show

# Set apt-cacher-ng proxy
./tools/debian-forge-config apt-proxy http://localhost:3142

# Set any configuration value
./tools/debian-forge-config set build default_suite trixie

Collaboration Workflow

For New Collaborators:

1. Clone the repository
2. Run ./tools/debian-forge-config setup
3. Edit config/debian-forge.local.conf with your settings
4. Your local settings won't affect others

For Existing Collaborators:

1. Your debian-forge.local.conf is already configured
2. Update settings as needed using the CLI tool
3. Your changes remain local

For Project Updates:

1. Default configuration changes are tracked in git
2. Your local overrides are preserved
3. You can merge new default settings as needed

File Locations

• Default config: config/debian-forge.conf
• Your local config: config/debian-forge.local.conf (create this)
• Template: config/debian-forge.local.conf.example
• CLI tool: tools/debian-forge-config

Troubleshooting

Configuration not loading?

• Check that config/debian-forge.local.conf exists
• Verify file permissions
• Use ./tools/debian-forge-config show to debug

Proxy not working?

• Verify your proxy URL is correct
• Check that apt-cacher-ng is running
• Use environment variable override for testing

Settings not taking effect?

• Remember the priority order
• Stage options override configuration files
• Use ./tools/debian-forge-config show to see current values

Debian version compatibility?

• We support Debian 13+ (Trixie and newer)
• Older releases may have compatibility issues
• Use trixie (stable) for production builds
• Use forky (testing) for development