add Debian packaging and repository infrastructure

docs/debian-repository.md

@@ -0,0 +1,168 @@
+# Deb-Mock Debian Repository
+
+This document describes the setup and management of the Deb-Mock Debian repository hosted on the Forgejo server.
+
+## Repository Information
+
+- **URL**: http://debian.raines.xyz
+- **Distribution**: unstable
+- **Component**: main
+- **Architectures**: amd64, arm64, i386, all, source
+
+## Setup Instructions
+
+### 1. Server Setup
+
+Run the setup script on the Forgejo server:
+
+```bash
+sudo ./scripts/setup-debian-repo.sh
+```
+
+This script will:
+- Install required packages (reprepro, nginx)
+- Create the repository structure
+- Set up nginx configuration
+- Generate GPG signing key
+- Configure proper permissions
+
+### 2. Client Setup
+
+To use the repository on a Debian system:
+
+```bash
+# Add the repository GPG key
+wget -O - http://debian.raines.xyz/deb-mock.gpg.key | sudo apt-key add -
+
+# Add the repository to sources.list
+echo 'deb http://debian.raines.xyz unstable main' | sudo tee /etc/apt/sources.list.d/deb-mock.list
+
+# Update package lists
+sudo apt update
+
+# Install deb-mock
+sudo apt install -y deb-mock
+```
+
+## CI/CD Integration
+
+The repository is automatically updated through Forgejo Actions:
+
+### Build Workflow
+
+The `.forgejo/workflows/build-deb.yml` workflow:
+
+1. **Builds** the Debian package from source
+2. **Tests** the package functionality
+3. **Creates** a local repository structure
+4. **Publishes** the package to the repository (on tags)
+
+### Manual Upload
+
+To manually upload a package to the repository:
+
+```bash
+# Build the package
+dpkg-buildpackage -us -uc -b
+
+# Upload to repository
+sudo ./scripts/upload-to-repo.sh
+```
+
+## Repository Management
+
+### Adding Packages
+
+```bash
+# Add a package to the repository
+sudo reprepro -b /var/www/debian-repo includedeb unstable /path/to/package.deb
+
+# Update repository metadata
+sudo reprepro -b /var/www/debian-repo export unstable
+```
+
+### Listing Packages
+
+```bash
+# List all packages in the repository
+sudo reprepro -b /var/www/debian-repo list unstable
+
+# List packages for specific architecture
+sudo reprepro -b /var/www/debian-repo list unstable deb-mock
+```
+
+### Removing Packages
+
+```bash
+# Remove a package from the repository
+sudo reprepro -b /var/www/debian-repo remove unstable deb-mock
+
+# Update repository metadata
+sudo reprepro -b /var/www/debian-repo export unstable
+```
+
+## Repository Structure
+
+```
+/var/www/debian-repo/
+├── conf/
+│   ├── distributions    # Repository configuration
+│   └── options         # Reprepro options
+├── dists/
+│   └── unstable/
+│       └── main/
+│           ├── binary-amd64/
+│           ├── binary-arm64/
+│           ├── binary-i386/
+│           └── source/
+├── pool/
+│   └── main/
+│       └── d/
+│           └── deb-mock/
+│               └── deb-mock_*.deb
+├── incoming/           # Package upload directory
+└── deb-mock.gpg.key   # Public GPG key
+```
+
+## Security
+
+### GPG Signing
+
+The repository is signed with a GPG key:
+- **Email**: deb-mock@raines.xyz
+- **Key Type**: RSA 4096-bit
+- **Public Key**: Available at http://debian.raines.xyz/deb-mock.gpg.key
+
+### Access Control
+
+- Repository files are owned by `www-data:www-data`
+- Nginx serves the repository with directory listing enabled
+- GPG key is required for package verification
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Package not found**: Ensure the package architecture matches the repository
+2. **GPG key errors**: Re-download the public key from the repository
+3. **Repository not accessible**: Check nginx configuration and permissions
+
+### Logs
+
+- **Nginx logs**: `/var/log/nginx/access.log` and `/var/log/nginx/error.log`
+- **Reprepro logs**: Check system logs for reprepro operations
+
+### Maintenance
+
+Regular maintenance tasks:
+
+```bash
+# Clean up old package versions
+sudo reprepro -b /var/www/debian-repo deleteunreferenced
+
+# Update repository metadata
+sudo reprepro -b /var/www/debian-repo export unstable
+
+# Check repository health
+sudo reprepro -b /var/www/debian-repo checkpool
+```