jasonwitty · jasonwitty · Nov 21, 2025 · Nov 21, 2025 · Nov 21, 2025 · Nov 21, 2025
diff --git a/.github/workflows/build-deb.yml b/.github/workflows/build-deb.yml
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,16 @@
 /target
 .vscode/
 /socktop-wasm-test/target
+/.cargo/
 
 # Documentation files from development sessions (context-specific, not for public repo)
 /OPTIMIZATION_PROCESS_DETAILS.md
 /THREAD_SUPPORT.md
+
+# APT Repository - Safety: Never commit private keys!
+*.asc
+*-private.key
+*-secret.key
+gpg-private-backup.key
+secring.gpg
+# Note: Release.gpg, InRelease, and KEY.gpg (public) ARE safe to commit
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/DEBIAN_PACKAGING_SUMMARY.md b/DEBIAN_PACKAGING_SUMMARY.md
@@ -0,0 +1,156 @@
+# Debian Packaging Implementation Summary
+
+## Overview
+
+Successfully implemented Debian packaging for socktop using `cargo-deb`, with GitHub Actions automation for building packages for both AMD64 and ARM64 architectures.
+
+## Branches Created
+
+1. **`feature/debian-packaging`** - Main branch with debian packaging implementation
+2. **`feature/man-pages`** - Separate branch for man pages work (to be researched further)
+
+## What Was Added
+
+### 1. Cargo.toml Updates
+
+Both `socktop/Cargo.toml` and `socktop_agent/Cargo.toml` were updated with:
+- `[package.metadata.deb]` sections
+- Package metadata (maintainer, description, dependencies)
+- Asset definitions (binaries, documentation)
+- Systemd service configuration (agent only)
+
+### 2. Systemd Service
+
+**File**: `socktop_agent/socktop-agent.service`
+- Runs as `socktop` user/group
+- Listens on port 3000 by default
+- Security hardening enabled
+- Disabled by default (user must explicitly enable)
+
+### 3. Maintainer Scripts
+
+**Directory**: `socktop_agent/debian/`
+
+- **`postinst`**: Creates `socktop` user/group, sets up `/var/lib/socktop` directory
+- **`postrm`**: Cleanup on package removal/purge
+
+### 4. GitHub Actions Workflow
+
+**File**: `.github/workflows/build-deb.yml`
+
+Features:
+- Builds for both x86_64 and ARM64
+- Triggered on:
+  - Push to `master` or `feature/debian-packaging`
+  - Pull requests to `master`
+  - Version tags (v*)
+  - Manual workflow dispatch
+- Creates artifacts:
+  - `debian-packages-amd64`
+  - `debian-packages-arm64`
+  - `all-debian-packages` (combined)
+  - `checksums` (SHA256SUMS)
+- Automatic GitHub releases for version tags
+
+### 5. Documentation
+
+**File**: `docs/DEBIAN_PACKAGING.md`
+
+Comprehensive guide covering:
+- Building packages locally
+- Cross-compilation for ARM64
+- Installation and configuration
+- Using GitHub Actions artifacts
+- Creating local APT repositories
+- Troubleshooting
+
+## Package Details
+
+### socktop (TUI Client)
+- **Binary**: `/usr/bin/socktop`
+- **Size**: ~3.5 MB (x86_64)
+- **Dependencies**: Auto-detected
+
+### socktop_agent (Daemon)
+- **Binary**: `/usr/bin/socktop_agent`
+- **Service**: `socktop-agent.service`
+- **User/Group**: `socktop` (created automatically)
+- **State directory**: `/var/lib/socktop`
+- **Size**: ~6.7 MB (x86_64)
+- **Dependencies**: Auto-detected
+
+## Testing
+
+Both packages successfully built locally:
+```
+✓ socktop_1.50.0-1_amd64.deb
+✓ socktop-agent_1.50.1-1_amd64.deb
+```
+
+Verified:
+- Package contents (dpkg -c)
+- Package metadata (dpkg -I)
+- Systemd service file inclusion
+- Maintainer scripts inclusion
+- Documentation inclusion
+
+## Usage
+
+### For Users
+
+Download pre-built packages from GitHub Actions artifacts:
+1. Go to Actions tab
+2. Select latest "Build Debian Packages" run
+3. Download architecture-specific artifact
+4. Install: `sudo dpkg -i socktop*.deb`
+
+### For Developers
+
+Build locally:
+```bash
+cargo install cargo-deb
+cargo deb --package socktop
+cargo deb --package socktop_agent
+```
+
+Cross-compile for ARM64:
+```bash
+rustup target add aarch64-unknown-linux-gnu
+sudo apt install gcc-aarch64-linux-gnu libc6-dev-arm64-cross
+cargo deb --package socktop --target aarch64-unknown-linux-gnu
+```
+
+## Next Steps
+
+To get packages in official APT repositories:
+
+1. **Short term**: Host packages on GitHub Releases (automated)
+2. **Medium term**: Create PPA for Ubuntu users
+3. **Long term**: Submit to Debian/Ubuntu official repositories
+
+## Files Modified/Created
+
+```
+Modified:
+  socktop/Cargo.toml
+  socktop_agent/Cargo.toml
+
+Created:
+  .github/workflows/build-deb.yml
+  docs/DEBIAN_PACKAGING.md
+  socktop_agent/socktop-agent.service
+  socktop_agent/debian/postinst
+  socktop_agent/debian/postrm
+```
+
+## Commit
+
+```
+532ed16 Add Debian packaging support with cargo-deb
+```
+
+## Resources
+
+- [cargo-deb documentation](https://github.com/kornelski/cargo-deb)
+- [Debian Policy Manual](https://www.debian.org/doc/debian-policy/)
+- Full documentation in `docs/DEBIAN_PACKAGING.md`
diff --git a/README.md b/README.md
@@ -51,15 +51,23 @@ exec bash   # or: exec zsh / exec fish
 
 Windows (for the brave): install from https://rustup.rs with the MSVC toolchain. Yes, you’ll need Visual Studio Build Tools. You chose Windows — enjoy the ride.
 
-### Raspberry Pi / Ubuntu / PopOS (required)
+### Raspberry Pi / Ubuntu / PopOS (required for GPU support)
 
-Install GPU support with apt command below
+**Note:** GPU monitoring is only supported on x86_64 and aarch64 (64-bit ARM) platforms. ARMv7 (32-bit) and RISC-V builds do not include GPU support.
+
+For 64-bit systems with GPU support:
 
 ```bash
 sudo apt-get update
 sudo apt-get install libdrm-dev libdrm-amdgpu1
 ```
 
+For ARMv7 (32-bit Raspberry Pi), build with `--no-default-features` to disable GPU support:
+
+```bash
+cargo build --release -p socktop_agent --no-default-features
+```
+
 _Additional note for Raspberry Pi users. Please update your system to use the newest kernel available through app, kernel version 6.6+ will use considerably less overall CPU to run the agent. For example on a rpi4 the kernel < 6.6 the agent will consume .8 cpu but on the same hardware on > 6.6 the agent will consume only .2 cpu. (these numbers indicate continuous polling at web socket endpoints, when not in use the usage is 0)_
 
 ---

diff --git a/apt-repo/KEY.gpg b/apt-repo/KEY.gpg
@@ -0,0 +1,42 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+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
+Dg==
+=AaPQ
+-----END PGP PUBLIC KEY BLOCK-----
diff --git a/apt-repo/README.md b/apt-repo/README.md
@@ -0,0 +1,38 @@
+# socktop APT Repository
+
+This repository contains Debian packages for socktop and socktop-agent.
+
+## Adding this repository
+
+Add the repository to your system:
+
+```bash
+# Add the GPG key
+curl -fsSL https://jasonwitty.github.io/socktop/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/socktop-archive-keyring.gpg
+
+# Add the repository
+echo "deb [signed-by=/usr/share/keyrings/socktop-archive-keyring.gpg] https://jasonwitty.github.io/socktop stable main" | sudo tee /etc/apt/sources.list.d/socktop.list
+
+# Update and install
+sudo apt update
+sudo apt install socktop socktop-agent
+```
+
+## Manual Installation
+
+You can also download and install packages manually from the `pool/main/` directory.
+
+```bash
+wget https://jasonwitty.github.io/socktop/pool/main/socktop_VERSION_ARCH.deb
+sudo dpkg -i socktop_VERSION_ARCH.deb
+```
+
+## Supported Architectures
+
+- amd64 (x86_64)
+- arm64 (aarch64)
+- armhf (32-bit ARM)
+
+## Building from Source
+
+See the main repository at https://github.com/jasonwitty/socktop
diff --git a/apt-repo/dists/stable/InRelease b/apt-repo/dists/stable/InRelease
@@ -0,0 +1,32 @@
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA512
+
+Origin: socktop
+Label: socktop
+Suite: stable
+Codename: stable
+Architectures: amd64 arm64 armhf
+Components: main
+Description: socktop APT repository
+Date: Sun, 23 Nov 2025 04:05:21 +0000
+MD5Sum:
+ 0bddefb2f13cb7c86cd05fe1ce20310f 1549 main/binary-amd64/Packages
+ 674f0e552cbb7dc65380651a2a8d279e 799 main/binary-amd64/Packages.gz
+SHA256:
+ babfbb4839e7fdfbc83742c16996791b0402a1315889b530330b338380398263 1549 main/binary-amd64/Packages
+ f8c48d0f7bf53eb02c6dbf5f1cdd046fe71b87273cf763c5bb2e95d9757a7a82 799 main/binary-amd64/Packages.gz
+
+-----BEGIN PGP SIGNATURE-----
+
+iQGzBAEBCgAdFiEEHnVWqAU5uDlLwoINESwaeYRl+/IFAmkiiAYACgkQESwaeYRl
++/KBsAv/eYhnK/XrNtPhLyw/zX2cGfUtBsBZrypFhV/n+TvudAIwQaqxDEvLlBUn
+HBAhMKDQXGs7V45+nOgDX4rKWUqJh4SPbJgNbVte2PX7U+hsMpZBsYp3vkjApgTO
+pq2CCkViyBXgTY+6vUigtvfJ9afTTWI6Qm4dLXZ7hxErBxgHQyowOoO/sF92cNOu
+AosBMpE+qSy7sVqJU5g/JXJh0kddKFotXHSGA1kFMzJafJC/n5nLrusDzFJRQqyH
+Io+6inYWjlb5o79z0tJzAvG1mgplLRppMBjoVJ/RJ+gT+QE70kokR6wvsgDqsKNd
+mvB0TNj0zY0g6Is6V3XMyf0u+6BtLTbua913HPiqBfErgeV58vzsst+y0It42TXi
+aw+UF2Kw/YhPq1rZFxgnAVcMja3qlXWpH57gmgIPovBCsPsiywWiHLsSHRzAI22b
+zeTsUST/4toR/ruZVbUZvWoWAR4tzsSuwXJFx/hhinTQQTNHErXASOX986UaL9L7
+o2/pTKLe
+=IeBY
+-----END PGP SIGNATURE-----
diff --git a/apt-repo/dists/stable/Release b/apt-repo/dists/stable/Release
@@ -0,0 +1,14 @@
+Origin: socktop
+Label: socktop
+Suite: stable
+Codename: stable
+Architectures: amd64 arm64 armhf
+Components: main
+Description: socktop APT repository
+Date: Sun, 23 Nov 2025 04:05:21 +0000
+MD5Sum:
+ 0bddefb2f13cb7c86cd05fe1ce20310f 1549 main/binary-amd64/Packages
+ 674f0e552cbb7dc65380651a2a8d279e 799 main/binary-amd64/Packages.gz
+SHA256:
+ babfbb4839e7fdfbc83742c16996791b0402a1315889b530330b338380398263 1549 main/binary-amd64/Packages
+ f8c48d0f7bf53eb02c6dbf5f1cdd046fe71b87273cf763c5bb2e95d9757a7a82 799 main/binary-amd64/Packages.gz
diff --git a/apt-repo/dists/stable/Release.gpg b/apt-repo/dists/stable/Release.gpg
@@ -0,0 +1,14 @@
+-----BEGIN PGP SIGNATURE-----
+
+iQGzBAABCgAdFiEEHnVWqAU5uDlLwoINESwaeYRl+/IFAmkiiAEACgkQESwaeYRl
++/KzeAv+OUIbxud5FboerwpAJULV+rS3+VX4kvwg/daVZ3yX3tJNrsyNCHgmWLVu
+fLeEFFc2Ax9GvFW4jrbxRAGD+3TXQEEFkb5lGzYyDjlgVzR6wLiVTTrmzWoK+cbB
+4DMozqeLiZFfQjq4UFn3+mwiYFX9Dj7PVF0M60XAUJSObbJFmaEPZIfx6wcZfkiL
+lLLk1eeU5MPiyudPOhVGgaD76KrUCw+8DBNKoCKIEcCY0LvuKtUK8mWYXRSPSved
+4Znd3QZz063Z6R+Lj1XlGLoTPResna28T/Nca+2JgLhbrihsLMcHoFxmrvFP9FpT
+MChKngj7NnGt0yqHH5J16hdwMra/vvhmF0yoQ0loIcy+q06tYEqOcau8tvAjfbId
+k3rgQgnxxVE8WUmV9Bugp7jhNMO+ImKWMwzEr6wGd9ZHqpknUlAaWeO73VP+qtAN
+6mEqWhkqvXGg+srH6qp3Sg0W28dYG29X3Kx8jOp7HeyvA/gLZRN7L+bq/XaA7WFA
+1hba6LIY
+=QoLf
+-----END PGP SIGNATURE-----
diff --git a/apt-repo/dists/stable/main/binary-amd64/Packages b/apt-repo/dists/stable/main/binary-amd64/Packages
@@ -0,0 +1,38 @@
+Package: socktop
+Version: 1.50.0-1
+Architecture: amd64
+Maintainer: Jason Witty <[email protected]>
+Installed-Size: 3459
+Filename: pool/main/socktop_1.50.0-1_amd64.deb
+Size: 1278940
+MD5sum: 0215e178e306d9379669065e8c78582b
+SHA1: 04e0416389f5cecd584fd1f6b3568711f2645eee
+SHA256: 69eb04b1de48541c95950a97b16357fcd9c51ffaceb143f63de4a9d758fad297
+Section: admin
+Priority: optional
+Homepage: https://github.com/jasonwitty/socktop
+Description: Remote system monitor over WebSocket, TUI like top
+ socktop is a remote system monitor with a rich terminal user interface (TUI)
+ that connects to remote hosts running the socktop_agent over WebSocket. It
+ provides real-time monitoring of CPU, memory, processes, and more with an
+ interface similar to the traditional 'top' command.
+
+Package: socktop-agent
+Version: 1.50.2-1
+Architecture: amd64
+Maintainer: Jason Witty <[email protected]>
+Installed-Size: 6793
+Filename: pool/main/socktop-agent_1.50.2-1_amd64.deb
+Size: 1896272
+MD5sum: 22e78d03e83dcf84d6ec4a009b285902
+SHA1: 26a9f4fedfdba06a047044027223f2944cf72ba6
+SHA256: 11922af475146f60347a9c52cff4bbce1ce524bdb4293b2c436f3c71876e17d5
+Section: admin
+Priority: optional
+Homepage: https://github.com/jasonwitty/socktop
+Description: Socktop agent daemon. Serves host metrics over WebSocket.
+ socktop_agent is the daemon component that runs on remote hosts to collect and
+ serve system metrics over WebSocket. It gathers CPU, memory, disk, network,
+ GPU, and process information that can be monitored remotely by the socktop TUI
+ client.
+
diff --git a/apt-repo/dists/stable/main/binary-amd64/Packages.gz b/apt-repo/dists/stable/main/binary-amd64/Packages.gz
diff --git a/apt-repo/dists/stable/main/binary-amd64/Release b/apt-repo/dists/stable/main/binary-amd64/Release
@@ -0,0 +1,5 @@
+Archive: stable
+Component: main
+Origin: socktop
+Label: socktop
+Architecture: amd64