aitbc/.windsurf/plans/distribution-binaries-plan.md

description

description
Distribution & Binaries Workflow for Debian Stable Miner

Distribution & Binaries Workflow

This workflow covers the creation and distribution of Debian stable miner binaries.

Prerequisites

• Debian stable build machine
• PyInstaller or similar packaging tool
• GitHub Releases configured
• Code signing certificates (for production)
• vLLM integration requirements

Steps

1. Debian Stable Miner Binary

1. Set up build environment for Debian stable

   • Debian stable (bookworm) build machine
   • Python 3.13+ with PyInstaller
   • CUDA Toolkit (for GPU support)
   • System dependencies: build-essential, python3-dev, python3-venv

2. Create PyInstaller spec files

   • File: scripts/gpu/miner.spec
   • Define entry point: scripts/gpu/gpu_miner_host.py
   • Include all dependencies
   • Configure hidden imports
   • Set icon and metadata

3. Build binary for Debian stable

   # Debian stable
   pyinstaller --onefile --name aitbc-miner-debian scripts/gpu/miner.spec
   

4. Test binary

   • Run binary on Debian stable
   • Verify GPU detection works
   • Test job submission and processing
   • Verify logging and error handling

5. Package binary with dependencies

   • Create installation script for Debian stable
   • Include README with Debian-specific instructions
   • Bundle configuration templates
   • Add verification checksums

2. vLLM Integration for Optimized LLM Inference

1. Research vLLM integration

   • Review vLLM documentation
   • Analyze compatibility with existing Ollama integration
   • Evaluate performance benefits
   • Check hardware requirements

2. Implement vLLM integration

   • Add vLLM dependency to requirements
   • Create vLLM service wrapper
   • Implement model loading with vLLM
   • Add vLLM-specific configuration options

3. Test vLLM integration

   • Benchmark performance vs Ollama
   • Test with various LLM models
   • Verify GPU utilization
   • Check memory usage

4. Create fallback mechanism

   • Implement Ollama as fallback
   • Add automatic model selection
   • Configure graceful degradation
   • Document vLLM vs Ollama trade-offs

3. Binary Distribution via GitHub Releases

1. Create GitHub Actions workflow

   • File: .github/workflows/build-binaries.yml
   • Trigger on version tags (e.g., v*.*.*)
   • Build for Debian stable
   • Upload artifacts to workflow

2. Configure automatic release creation

   • Use GitHub Actions to create release on tag
   • Attach binaries as release assets
   • Generate release notes from CHANGELOG
   • Sign binaries (if code signing available)

3. Create release process

   # Tag release
   git tag -a v0.1.0 -m "Release v0.1.0"
   git push origin v0.1.0
   
   # GitHub Actions will:
   # 1. Build binary for Debian stable
   # 2. Create GitHub Release
   # 3. Attach binaries as assets
   

4. Test release process

   • Create test release tag
   • Verify automatic build works
   • Check release creation
   • Verify asset attachments
   • Test download and installation

4. Automatic Binary Building in CI/CD

1. Enhance existing CI/CD pipeline

   • Add binary build step to existing workflows
   • Configure build for Debian stable
   • Cache build dependencies
   • Optimize build times

2. Set up build agent

   • Configure GitHub Actions runner
   • Use self-hosted runner for Debian stable builds

3. Add build notifications

   • Notify on build failures
   • Send build status to Slack/Email
   • Track build metrics
   • Monitor build queue times

4. Implement build artifacts

   • Store build artifacts for debugging
   • Keep last N builds
   • Configure artifact retention policy
   • Enable artifact download for testing

5. Installation Guides and Verification Instructions

1. Create Debian stable installation guide

   • Debian: docs/installation/debian-miner.md

2. Installation guide sections

   • System requirements
   • Prerequisites (GPU drivers, CUDA)
   • Download instructions
   • Installation steps
   • Configuration
   • Verification
   • Troubleshooting

3. Create verification script

   • Script: scripts/installation/verify-install.sh
   • Check binary integrity with checksums
   • Verify GPU detection
   • Test basic functionality
   • Output verification report

4. Add checksums to releases

   • Generate SHA256 checksums for each binary
   • Include checksums in release notes
   • Provide verification instructions
   • Automate checksum generation

6. Binary Signature Verification

1. Set up code signing

   • Obtain code signing certificates
   • Configure signing tools
   • Set up certificate storage (GitHub Secrets)
   • Test signing process

2. Sign binaries

   • Sign Linux binaries with GPG
   • Sign Windows binaries with Authenticode
   • Sign macOS binaries with Apple Developer ID
   • Add signatures to release assets

3. Create verification instructions

   • Document signature verification process
   • Provide GPG public key
   • Include verification commands
   • Add to installation guides

4. Automate signing in CI/CD

   • Add signing step to build workflow
   • Configure certificate access
   • Test signed binary distribution
   • Verify signature verification works

Verification

• Binary builds successfully for Debian stable
• Binary runs correctly on Debian stable
• vLLM integration tested and documented
• GitHub Actions workflow builds binary automatically
• Releases created automatically on tags
• Installation guide complete for Debian stable
• Verification scripts work correctly
• Code signing configured and tested
• Signature verification documented

Troubleshooting

• Build fails on Debian stable: Check Debian-specific dependencies, verify Python version, test build locally
• Binary doesn't run: Check PyInstaller spec file, verify dependencies, test on clean Debian system
• vLLM integration fails: Check vLLM version compatibility, verify GPU drivers, test with simple model
• Release creation fails: Check GitHub token permissions, verify workflow configuration, test with manual release
• Signature verification fails: Check certificate validity, verify signing process, test verification commands

Related Files

• scripts/gpu/miner.spec
• scripts/gpu/gpu_miner_host.py
• .github/workflows/build-binaries.yml
• docs/installation/debian-miner.md
• scripts/installation/verify-install.sh