socktop/SETUP_GITHUB_PAGES.md

Setting Up GitHub Pages for socktop APT Repository

This guide walks you through the initial setup of your APT repository on GitHub Pages using the gh-pages branch.

Prerequisites

• You've run ./scripts/setup-apt-repo.sh or manually created apt-repo/
• apt-repo/ contains signed packages and metadata
• You have a GitHub repository for socktop

Step-by-Step Setup

1. Verify Your Local Repository

First, make sure everything is ready:

# Check that apt-repo exists and has content
ls -la apt-repo/

# You should see:
# - dists/stable/Release, Release.gpg, InRelease
# - pool/main/*.deb
# - KEY.gpg
# - index.html, README.md

2. Create and Switch to gh-pages Branch

# Create a new orphan branch (no history from main)
git checkout --orphan gh-pages

# Remove all files from staging
git rm -rf .

Important: This creates a completely separate branch. Don't worry - your main branch is safe!

3. Copy APT Repository to Root

# Copy CONTENTS of apt-repo to root of gh-pages
cp -r apt-repo/* .

# Remove the apt-repo directory itself
rm -rf apt-repo

# Verify the structure
ls -la

# You should see in the current directory:
# - dists/
# - pool/
# - KEY.gpg
# - index.html
# - README.md

Why root? GitHub Pages can only serve from:

• / (root) - what we're doing
• /docs directory
• NOT from custom directories like /apt-repo

4. Commit and Push

# Add all files
git add .

# Commit
git commit -m "Initialize APT repository for GitHub Pages"

# Push to gh-pages branch
git push -u origin gh-pages

5. Return to Main Branch

# Switch back to your main development branch
git checkout main

# Verify you're back on main
git branch
# Should show: * main

6. Enable GitHub Pages

1. Go to your repository on GitHub
2. Click Settings (top right)
3. Click Pages (left sidebar)
4. Under "Build and deployment":
   • Source: Deploy from a branch
   • Branch: gh-pages
   • Folder: / (root)
   • Click Save

7. Wait for Deployment

GitHub will deploy your site. This usually takes 1-2 minutes.

You can watch the progress:

• Go to Actions tab
• Look for "pages build and deployment" workflow

8. Verify Your Repository is Live

Once deployed, your repository will be at:

https://YOUR-USERNAME.github.io/socktop/

Test it:

# Check the public key is accessible
curl -I https://YOUR-USERNAME.github.io/socktop/KEY.gpg

# Should return: HTTP/2 200

# Check the Release file
curl -I https://YOUR-USERNAME.github.io/socktop/dists/stable/Release

# Should return: HTTP/2 200

9. Test Installation (Optional but Recommended)

On a Debian/Ubuntu VM or system:

# Add GPG key
curl -fsSL https://YOUR-USERNAME.github.io/socktop/KEY.gpg | \
    sudo gpg --dearmor -o /usr/share/keyrings/socktop-archive-keyring.gpg

# Add repository
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

# Update package lists
sudo apt update

# You should see:
# Get:1 https://YOUR-USERNAME.github.io/socktop stable InRelease [xxx B]

# Install packages
sudo apt install socktop socktop-agent

# Verify
socktop --version

Understanding the Two Branches

After setup, you'll have two branches:

main branch (development)

main/
├── src/
├── Cargo.toml
├── scripts/
├── docs/
├── apt-repo/          ← Local build artifact (not published)
└── ...

Purpose: Source code, development, building packages

gh-pages branch (published)

gh-pages/
├── dists/
├── pool/
├── KEY.gpg
├── index.html         ← Customize this for a nice landing page!
└── README.md

Purpose: Published APT repository served by GitHub Pages

Workflow Going Forward

Manual Updates

When you release a new version:

# 1. On main branch, build new packages
git checkout main
cargo deb --package socktop
cargo deb --package socktop_agent

# 2. Update local apt-repo
./scripts/add-package-to-repo.sh target/debian/socktop_*.deb
./scripts/add-package-to-repo.sh target/debian/socktop-agent_*.deb
./scripts/sign-apt-repo.sh apt-repo stable YOUR-GPG-KEY-ID

# 3. Switch to gh-pages and update
git checkout gh-pages
cp -r apt-repo/* .
git add .
git commit -m "Release v1.51.0"
git push origin gh-pages

# 4. Return to main
git checkout main

Automated Updates (Recommended)

Set up GitHub Actions to do this automatically:

1. Add GitHub Secrets (Settings → Secrets → Actions):

   • GPG_PRIVATE_KEY - Your exported private key
   • GPG_KEY_ID - Your GPG key ID
   • GPG_PASSPHRASE - Your GPG passphrase (if any)

2. Tag and push:

   git tag v1.51.0
   git push origin main --tags
   

3. GitHub Actions will automatically:

   • Build packages for AMD64 and ARM64
   • Update apt-repo
   • Sign with your GPG key
   • Push to gh-pages
   • Create GitHub Release

See .github/workflows/publish-apt-repo.yml for details.

Customizing Your GitHub Pages Site

The gh-pages branch contains index.html which users see when they visit: https://YOUR-USERNAME.github.io/socktop/

You can customize this! On the gh-pages branch:

git checkout gh-pages

# Edit index.html
nano index.html

# Add features, badges, screenshots, etc.

git add index.html
git commit -m "Improve landing page"
git push origin gh-pages

git checkout main

Troubleshooting

"404 Not Found" on GitHub Pages

Check:

• Settings → Pages shows "Your site is live at..."
• Wait 2-3 minutes after pushing
• Verify branch is gh-pages and folder is /
• Check Actions tab for deployment errors

"Repository not found" when installing

Check:

• URL is correct: https://USERNAME.github.io/REPO/ (no trailing /apt-repo)
• Files exist at the URLs:

  curl -I https://USERNAME.github.io/REPO/dists/stable/InRelease
  curl -I https://USERNAME.github.io/REPO/KEY.gpg
  

"GPG error" when installing

Check:

• Repository is signed: ls gh-pages/dists/stable/Release.gpg
• Users imported the key: curl https://USERNAME.github.io/REPO/KEY.gpg | gpg --import

Changes not appearing

Check:

• You committed and pushed to gh-pages (not main)
• Wait 1-2 minutes for GitHub to redeploy
• Clear browser cache if viewing index.html
• For apt: sudo apt clean && sudo apt update

Success Checklist

After completing this guide, you should have:

• gh-pages branch created and pushed
• GitHub Pages enabled and deployed
• Site accessible at https://USERNAME.github.io/socktop/
• KEY.gpg downloadable
• dists/stable/InRelease accessible
• Packages in pool/main/*.deb downloadable
• Successfully tested installation on a test system
• Understand the workflow for future updates

Next Steps

1. Update your main README.md with installation instructions
2. Set up GitHub Actions for automated releases
3. Customize index.html on gh-pages for a nice landing page
4. Test on multiple architectures (AMD64, ARM64)
5. Share your repository with users

Quick Reference

Switch branches:

git checkout main        # Development
git checkout gh-pages    # Published site

Update published site manually:

git checkout main
# ... build packages, update apt-repo ...
git checkout gh-pages
cp -r apt-repo/* .
git add . && git commit -m "Update" && git push
git checkout main

Your repository URL:

https://YOUR-USERNAME.github.io/socktop/

User installation command:

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
sudo apt update && sudo apt install socktop socktop-agent

---

Need help? See:

• QUICK_START_APT_REPO.md - Overall quick start
• docs/APT_REPOSITORY.md - Comprehensive guide
• docs/APT_WORKFLOW.md - Visual workflow diagrams