docs: add PACKAGING-GUIDE.md with install steps for Ubuntu and Fedora

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

1 files changed, 190 insertions, 0 deletions

diff --git a/docs/PACKAGING-GUIDE.md b/docs/PACKAGING-GUIDE.md
new file mode 100644
index 0000000..01a894a
--- /dev/null
+++ b/docs/PACKAGING-GUIDE.md
@@ -0,0 +1,190 @@
+# MeshBay — Installation Guide
+
+Four packages, all installed under `/opt/`:
+
+| Package | What it does |
+|---|---|
+| `meshbay-common` | Shared Python venv with all dependencies |
+| `meshbay-hub` | Identity authority and group registry (server) |
+| `meshbay-node` | Local file host, streaming, chat daemon |
+| `meshbay-client` | Desktop app (Electron) |
+
+Pick what you need: a desktop user installs **common + node + client**.
+A server running the hub installs **common + hub**.
+
+---
+
+## Ubuntu / Debian
+
+### Install
+
+```bash
+sudo dpkg -i meshbay-common_0.8.0_amd64.deb
+sudo dpkg -i meshbay-node_0.8.0_amd64.deb      # desktop machine
+sudo dpkg -i meshbay-hub_0.8.0_amd64.deb        # server only
+sudo dpkg -i meshbay-client_0.8.0_amd64.deb     # desktop machine
+```
+
+If dpkg complains about missing dependencies:
+
+```bash
+sudo apt-get install -f
+```
+
+### Uninstall
+
+```bash
+sudo dpkg --remove meshbay-client meshbay-hub meshbay-node meshbay-common
+sudo rm -rf /opt/meshbay-*
+```
+
+---
+
+## Fedora / RHEL
+
+### Install
+
+```bash
+sudo rpm -ivh meshbay-common-0.8.0-1.fc44.x86_64.rpm
+sudo rpm -ivh meshbay-node-0.8.0-1.fc44.noarch.rpm      # desktop machine
+sudo rpm -ivh meshbay-hub-0.8.0-1.fc44.noarch.rpm        # server only
+sudo rpm -ivh meshbay-client-0.8.0-1.fc44.x86_64.rpm     # desktop machine
+```
+
+### Uninstall
+
+```bash
+sudo rpm -e meshbay-client meshbay-hub meshbay-node meshbay-common
+```
+
+---
+
+## Post-install: Node (desktop user)
+
+### 1. Initialize
+
+```bash
+meshbay-node init
+```
+
+This creates `~/.config/meshbay/` with a default config and environment
+(including the TMDB API token for the Videos app).
+
+### 2. Create or join a group
+
+```bash
+meshbay-node group add --hub https://meshbay.org --upload-dir ~/Shared
+```
+
+Follow the interactive wizard to create a new group or accept an
+invitation.
+
+### 3. Start the service
+
+```bash
+systemctl --user enable --now meshbay-node
+loginctl enable-linger $USER    # keep serving when logged out
+```
+
+### 4. Launch the desktop app
+
+Open **MeshBay** from the applications menu, or:
+
+```bash
+meshbay
+```
+
+---
+
+## Post-install: Hub (server)
+
+### 1. Set up PostgreSQL
+
+```bash
+sudo -u postgres createuser meshbay
+sudo -u postgres createdb -O meshbay meshbay_hub
+```
+
+### 2. Generate the hub keypair
+
+```bash
+sudo meshbay-hub --generate-keys
+```
+
+This writes `/etc/meshbay/hub_private.pem`.
+
+### 3. Configure
+
+```bash
+sudo cp /opt/meshbay-hub/share/hub.toml.example /etc/meshbay/hub.toml
+sudo nano /etc/meshbay/hub.toml
+```
+
+Edit at minimum: the database URL and the listen address.
+
+Set the database password in `/etc/meshbay/hub.env`:
+
+```bash
+echo 'MESHBAY_DATABASE_URL=postgresql+asyncpg://meshbay:YOUR_PASSWORD@localhost/meshbay_hub' \
+  | sudo tee /etc/meshbay/hub.env
+sudo chmod 640 /etc/meshbay/hub.env
+sudo chown meshbay:meshbay /etc/meshbay/hub.env
+```
+
+### 4. Start
+
+```bash
+sudo systemctl enable --now meshbay-hub
+sudo journalctl -u meshbay-hub -f       # check logs
+```
+
+---
+
+## Firewall
+
+The packages ship passive firewall profiles (not auto-activated).
+
+### Chromecast / Smart TV casting (client)
+
+Opens TCP 19550-19553 (HTTP relay) and UDP 5353 (mDNS discovery).
+
+```bash
+# Fedora (firewalld)
+sudo firewall-cmd --permanent --add-service=meshbay-cast
+sudo firewall-cmd --reload
+
+# Ubuntu (ufw)
+sudo ufw allow "MeshBay Cast"
+```
+
+### Node admin UI
+
+Opens TCP 18000.
+
+```bash
+# Fedora (firewalld)
+sudo firewall-cmd --permanent --add-service=meshbay-node
+sudo firewall-cmd --reload
+
+# Ubuntu (ufw)
+sudo ufw allow "MeshBay Node"
+```
+
+---
+
+## Building packages from source
+
+On the target machine, from the repo checkout:
+
+```bash
+# Ubuntu / Debian
+bash packaging/build/build-packages.sh deb
+
+# Fedora
+bash packaging/build/build-packages.sh rpm
+```
+
+Packages are written to `/tmp/meshbay-build/out/`.
+
+Requirements: Python 3.12+, Node.js 22+ (for client), ImageMagick
+(for icon resizing), dpkg-deb or rpmbuild.