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

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.