Initialize APT repository

Source: feature/debian-packaging@a9366d069d Date: 2025-11-23 21:24:50 UTC
2025-11-23 13:24:50 -08:00
commit 5dbab9062c
16 changed files with 1464 additions and 0 deletions
@@ -0,0 +1,221 @@
+# Quick Start: Setting Up Your socktop APT Repository
+
+This guide will get your APT repository up and running in **under 10 minutes**.
+
+## Prerequisites
+
+- [ ] Debian packages built (or use GitHub Actions to build them)
+- [ ] GPG key for signing
+- [ ] GitHub repository with Pages enabled
+
+## Step 1: Create GPG Key (if needed)
+
+```bash
+# Generate a new key
+gpg --full-generate-key
+
+# Select:
+# - RSA and RSA (default)
+# - 4096 bits
+# - Key does not expire (or 2 years)
+# - Your name and email
+
+# Get your key ID
+gpg --list-secret-keys --keyid-format LONG
+# Look for the part after "rsa4096/" - that's your KEY-ID
+```
+
+## Step 2: Initialize Repository Locally
+
+```bash
+cd socktop
+
+# Create the repository structure
+./scripts/init-apt-repo.sh
+
+# Build packages (or download from GitHub Actions)
+cargo install cargo-deb
+cargo deb --package socktop
+cargo deb --package socktop_agent
+
+# Add packages to repository
+./scripts/add-package-to-repo.sh target/debian/socktop_*.deb
+./scripts/add-package-to-repo.sh target/debian/socktop-agent_*.deb
+
+# Sign the repository (replace YOUR-KEY-ID with actual key ID)
+./scripts/sign-apt-repo.sh apt-repo stable YOUR-KEY-ID
+
+# Update URLs with your GitHub username
+sed -i 's/YOUR-USERNAME/your-github-username/g' apt-repo/README.md apt-repo/index.html
+```
+
+## Step 3: Publish to GitHub Pages (gh-pages branch)
+
+```bash
+# Create gh-pages branch
+git checkout --orphan gh-pages
+git rm -rf .
+
+# Copy apt-repo CONTENTS to root (not the folder itself)
+cp -r apt-repo/* .
+rm -rf apt-repo
+
+# Commit and push
+git add .
+git commit -m "Initialize APT repository"
+git push -u origin gh-pages
+
+# Go back to main branch
+git checkout main
+```
+
+Then in GitHub:
+1. Go to **Settings → Pages**
+2. Source: **Deploy from a branch**
+3. Branch: **gh-pages** → **/ (root)** → **Save**
+
+Wait 1-2 minutes, then visit: `https://your-username.github.io/socktop/`
+
+## Step 4: Automate with GitHub Actions
+
+Add these secrets to your repository (Settings → Secrets → Actions):
+
+```bash
+# Export your private key
+gpg --armor --export-secret-key YOUR-KEY-ID
+
+# Copy the ENTIRE output and save as secret: GPG_PRIVATE_KEY
+```
+
+Add these three secrets:
+- **GPG_PRIVATE_KEY**: Your exported private key
+- **GPG_KEY_ID**: Your key ID (e.g., `ABC123DEF456`)
+- **GPG_PASSPHRASE**: Your key passphrase (leave empty if no passphrase)
+
+The workflow in `.github/workflows/publish-apt-repo.yml` will now:
+- Build packages for AMD64 and ARM64
+- Update the APT repository
+- Sign with your GPG key
+- Push to gh-pages automatically
+
+Trigger it by:
+- Creating a version tag: `git tag v1.50.0 && git push --tags`
+- Manual dispatch from GitHub Actions tab
+
+## Step 5: Test It
+
+On any Debian/Ubuntu system:
+
+```bash
+# Add your repository
+curl -fsSL https://your-username.github.io/socktop/KEY.gpg | \
+    sudo gpg --dearmor -o /usr/share/keyrings/socktop-archive-keyring.gpg
+
+echo "deb [signed-by=/usr/share/keyrings/socktop-archive-keyring.gpg] https://your-username.github.io/socktop stable main" | \
+    sudo tee /etc/apt/sources.list.d/socktop.list
+
+# Install
+sudo apt update
+sudo apt install socktop socktop-agent
+
+# Verify
+socktop --version
+socktop_agent --version
+```
+
+## Maintenance
+
+### Add a New Version
+
+```bash
+# Build new packages
+cargo deb --package socktop
+cargo deb --package socktop_agent
+
+# Add to repository
+./scripts/add-package-to-repo.sh target/debian/socktop_*.deb
+./scripts/add-package-to-repo.sh target/debian/socktop-agent_*.deb
+
+# Re-sign
+./scripts/sign-apt-repo.sh apt-repo stable YOUR-KEY-ID
+
+# Publish
+cd docs/apt  # or wherever your apt-repo is
+git add .
+git commit -m "Release v1.51.0"
+git push origin main
+```
+
+### Or Just Tag and Let GitHub Actions Do It
+
+```bash
+# Update version in Cargo.toml
+# Commit changes
+git add .
+git commit -m "Bump version to 1.51.0"
+
+# Tag and push
+git tag v1.51.0
+git push origin main --tags
+
+# GitHub Actions will:
+# - Build packages for AMD64 and ARM64
+# - Update gh-pages branch automatically
+# - Sign and publish!
+```
+
+## Troubleshooting
+
+### "Repository not signed" error
+
+Make sure you signed it:
+```bash
+./scripts/sign-apt-repo.sh apt-repo stable YOUR-KEY-ID
+ls apt-repo/dists/stable/Release*
+# Should show: Release, Release.gpg, InRelease, KEY.gpg
+```
+
+### "404 Not Found" on GitHub Pages
+
+1. Check Settings → Pages is enabled
+2. Wait 2-3 minutes for GitHub to deploy
+3. Verify the URL structure matches your settings
+
+### GitHub Actions not signing
+
+Check that all three secrets are set correctly:
+- Settings → Secrets and variables → Actions
+- Make sure GPG_PRIVATE_KEY includes the BEGIN/END lines
+- Test locally first
+
+## What's Next?
+
+✅ You now have a working APT repository!
+
+**Share it:**
+- Add installation instructions to your main README
+- Tweet/blog about it
+- Submit to awesome-rust lists
+
+**Improve it:**
+- Customize your GitHub Pages site (it's just HTML!)
+- Add more architectures (ARMv7)
+- Create multiple distributions (stable, testing)
+- Set up download statistics
+- Apply to Ubuntu PPA (Launchpad)
+- Eventually submit to official Debian repos
+
+## Full Documentation
+
+For detailed information, see:
+- `docs/APT_REPOSITORY.md` - Complete APT repository guide
+- `docs/DEBIAN_PACKAGING.md` - Debian packaging details
+- `DEBIAN_PACKAGING_SUMMARY.md` - Quick summary
+
+## Questions?
+
+Open an issue on GitHub or check the full documentation.
+
+---
+
+**Happy packaging! 📦**