# 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 one thing — **when the node runs**:

- **As a background service** (the default) — the node starts **at boot,
  before you even sign in**.
- **Automatically when I sign in to Windows** — a launcher in your Startup
  folder, no service.
- **Only while MeshBay is open** — the app starts the node and stops it when
  you quit.

Every choice also adds the Windows Firewall rules the app and the node need
(WebRTC, casting), so setup asks for **one administrator confirmation**: for the
service and the rules together, or for the rules alone. Running setup again (an
upgrade, a repair) keeps the choice it finds and asks nothing when the rules and
the service are already in place. The choice can be changed later on the
**Node** page (**Start automatically**).

**ffmpeg** — required for video streaming, **bundled in the installer by
default** (verified, checksummed, GPLv3-licensed; `LICENSE-ffmpeg.txt` ships
alongside it). Nothing to install separately.

### First run

Open MeshBay, choose the hub and sign in. **That is all**: the app sets the node
up for the account you signed in with, starts it the way you chose at install,
and links it to your account. **Node** and **Create group** appear in the
sidebar; nothing has to be typed in a terminal and no key has to be copied.

Two cases where the app does not do it on its own, because it would undo
something:

- the node was already set up for **another account or another hub** — the
  **Start** button on the Node page asks before switching it;
- your account is already linked to a node on **another machine** — linking
  this one would disconnect that one. The Node page shows this node's key;
  **Profile → Link Node** moves the link here if that is what you want.

The Node page's **Start / Stop / Restart** work in every mode, and its status
is the node's own: **Running** when it answers, **Stopped** only once no
`meshbay-node.exe` is left. If a node will not stop, the page says so and why.

The node logs to `%LOCALAPPDATA%\meshbay\state\node.log` — in service mode
that file is the only place it can tell you why it would not start.

Runtime data — `node.toml`, `keystore.enc`, `unlock.key`, `data\` — lives in
`%LOCALAPPDATA%\meshbay\` and **survives uninstall/reinstall**, in every 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 node, removes the sign-in launcher, and removes the
firewall rules and the boot-time service task with one administrator
confirmation (none if neither is there). 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.