path: root/docs/PACKAGING-GUIDE.md

# 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.9.0_amd64.deb
sudo dpkg -i meshbay-node_0.9.0_amd64.deb      # desktop machine
sudo dpkg -i meshbay-hub_0.9.0_amd64.deb        # server only
sudo dpkg -i meshbay-client_0.9.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.9.0-1.fc44.x86_64.rpm
sudo rpm -ivh meshbay-node-0.9.0-1.fc44.noarch.rpm      # desktop machine
sudo rpm -ivh meshbay-hub-0.9.0-1.fc44.noarch.rpm        # server only
sudo rpm -ivh meshbay-client-0.9.0-1.fc44.x86_64.rpm     # desktop machine
```

### Uninstall

```bash
sudo rpm -e meshbay-client meshbay-hub meshbay-node meshbay-common
```

---

## Windows

One installer, **`MeshBay-Setup-<version>.exe`**, carries the client **and** the
node (with `meshbay-common` inside it). There is no Windows hub.

### Install

Run the installer. It is **per-user** — no administrator prompt — and lands in
`%LOCALAPPDATA%\Programs\meshbay-client\`. The node daemon ships beside the app
at `resources\node-runtime\meshbay-node.exe`; the client finds it automatically.

**ffmpeg** is required for video streaming and is *not* in the installer unless
it was built with `-FfmpegDir`. Otherwise install it separately
(`winget install ffmpeg`) so the node finds it on `PATH`.

### First run

Open MeshBay and sign in. Use the **Node** page (or a terminal) to provision:

```
meshbay-node init
meshbay-node autostart install     # run the daemon at every sign-in (no admin)
```

Runtime data — `node.toml`, `keystore.enc`, `unlock.key`, `data\` — lives in
`%LOCALAPPDATA%\meshbay\` and **survives uninstall/reinstall**.

### Uninstall

*Apps & features → MeshBay → Uninstall*, or the Start-menu *Uninstall MeshBay*
entry. It stops a running daemon and removes the sign-in launcher; it does not
touch `%LOCALAPPDATA%\meshbay\` (the keystore).

### Build from source

See [`packaging/win/README.md`](../packaging/win/README.md). On a machine with
Node ≥ 22 and Python ≥ 3.12:

```powershell
cd packages\meshbay-client
npm run dist:win
```

---

## 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"
```

### Peer connections (node)

Opens inbound UDP 1024-65535. **Scope it to the LAN** — apply the firewalld
service to the zone holding the LAN interface, and give the ufw rule a
`from`. It does not belong in an internet-facing zone.

```bash
# Fedora (firewalld) — replace FedoraWorkstation with your LAN zone
sudo firewall-cmd --permanent --zone=FedoraWorkstation --add-service=meshbay-node
sudo firewall-cmd --reload

# Ubuntu (ufw)
sudo ufw allow from 192.168.1.0/24 app "MeshBay Node"

# a libvirt guest reaching the node on its own hypervisor: scope to the guest
# subnet, since traffic to the host's own address is not masqueraded
sudo ufw allow in on virbr0 from 192.168.200.0/24 app "MeshBay Node"
```

**Why a node needs this.** WebRTC binds an ephemeral UDP port per connection,
so there is no fixed port to open. A connection succeeds if *either* side can
initiate. Browsers publish their host candidate as an mDNS `<uuid>.local`
name, which `aioice` cannot resolve on any platform and discards — so the node
can never call a browser back, and the browser must call the node. A node that
refuses unsolicited inbound UDP is unreachable from every browser on its own
LAN, and falls back to reflexive candidates, which fail whenever both peers
share one public IP and the router will not hairpin.

The node's administration surface is unaffected: loopback only, see below.

The node's own administration surface is a loopback API (127.0.0.1 only,
per-run token) reached by the CLI and the desktop client's Node page. It is
never network-exposed and ships no firewall profile.

---

## 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.