diff options
| -rw-r--r-- | docs/PACKAGING-GUIDE.md | 190 |
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. |