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** and lands in
`%LOCALAPPDATA%\Programs\MeshBay\` without needing admin rights. The
node daemon ships beside the app at `resources\node-runtime\meshbay-node.exe`;
the client finds it automatically.

It asks two things, both skippable:

- **"Run MeshBay Node as a background service?"** — Yes starts the node **at
  boot, before you even sign in**, and needs one administrator confirmation
  (which also sets up the firewall rules, in the same step — see below). No
  keeps the normal per-user mode: the node starts when you sign in, with no
  admin needed, and you can turn autostart on later from the Node page.
- **(per-user mode only) "Allow MeshBay through Windows Firewall now?"** — one
  administrator confirmation adds the inbound rules the client and the node
  need for WebRTC and casting. Declining is fine — Windows shows its own
  "Allow access" dialog instead, the first time each is actually used.

Running setup again (an upgrade, a repair install) asks neither question if
the firewall rules are already there.

**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     # per-user mode: run at every sign-in (no admin)
meshbay-node service install       # service mode: run at boot (needs an elevated prompt)
```

The Node page's Start/Stop/Restart buttons work the same either way — they
drive the Scheduled Task when service mode is active, or the daemon process
directly otherwise.

Runtime data — `node.toml`, `keystore.enc`, `unlock.key`, `data\` — lives in
`%LOCALAPPDATA%\meshbay\` and **survives uninstall/reinstall**, in either mode
(service mode runs as your own account too — never LocalSystem — so nothing
about where your data lives changes).

### Uninstall

*Apps & features → MeshBay → Uninstall*, or the Start-menu *Uninstall MeshBay*
entry. It stops a running daemon and removes the sign-in launcher; it offers
(opt-in, one admin confirmation) to also remove the firewall rules and the
boot-time service task, if you set one up. None of this touches
`%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.