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
```bash
# 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
```bash
# 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
```bash
./tools/debian-forge-config show
```

## Configuration Options

### apt-cacher-ng Section
```ini
[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
```ini
[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
```ini
[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:

```bash
# 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:

```bash
# 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