debian-forge/generated_docs/DEPLOYMENT_GUIDE.md

Debian Forge Deployment Guide

Generated on: 2025-08-23 09:39:21

System Requirements

Hardware Requirements

• CPU: 4 cores minimum, 8+ cores recommended
• Memory: 8GB minimum, 16GB+ recommended
• Storage: 50GB minimum, SSD recommended
• Network: 1Gbps minimum, 10Gbps recommended

Software Requirements

• Operating System: Debian 12+ (Bookworm)
• Kernel: Linux 5.15+
• Python: 3.8+
• Database: SQLite (default) or PostgreSQL

Installation

Prerequisites

# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y python3 python3-pip python3-venv git
sudo apt install -y build-essential libssl-dev libffi-dev

# Install Go (for CLI and Composer)
sudo apt install -y golang-go

Source Installation

# Clone repositories
git clone <debian-forge-repo>
git clone <debian-forge-cli-repo>
git clone <debian-forge-composer-repo>

# Set up Python environment
cd debian-forge
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuration

Environment Configuration

# Create configuration file
cp config.example.yaml config.yaml

# Edit configuration
nano config.yaml

Database Configuration

• SQLite: Default, no additional configuration needed
• PostgreSQL: Configure connection parameters
• Database Initialization: Run setup scripts

Security Configuration

• SSL/TLS: Configure HTTPS certificates
• Firewall: Configure network security
• User Authentication: Set up initial admin user

Service Configuration

Systemd Service

[Unit]
Description=Debian Forge Service
After=network.target

[Service]
Type=simple
User=debian-forge
WorkingDirectory=/opt/debian-forge
ExecStart=/opt/debian-forge/venv/bin/python main.py
Restart=always

[Install]
WantedBy=multi-user.target

Nginx Configuration

server {
    listen 80;
    server_name debian-forge.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name debian-forge.example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Deployment Steps

1. System Preparation

• Verify system requirements
• Install prerequisites
• Configure system settings

2. Application Installation

• Clone source repositories
• Install dependencies
• Configure application

3. Service Setup

• Create system user
• Configure systemd service
• Set up reverse proxy

4. Initial Configuration

• Initialize database
• Create admin user
• Configure security settings

5. Testing and Validation

• Test service startup
• Verify web interface
• Test basic functionality

Monitoring and Maintenance

Health Checks

• Service Status: Check systemd service status
• Web Interface: Verify web interface accessibility
• Database Health: Check database connectivity
• Performance Metrics: Monitor system performance

Backup Procedures

• Configuration Files: Backup configuration directory
• Database: Regular database backups
• User Data: Backup user uploads and generated images