diff options
Diffstat (limited to 'docs/QUICKSTART.md')
| -rw-r--r-- | docs/QUICKSTART.md | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md new file mode 100644 index 0000000..9a418f2 --- /dev/null +++ b/docs/QUICKSTART.md @@ -0,0 +1,380 @@ +# MeshBay — Quickstart + +This guide takes one Linux machine, turns it into a MeshBay node, creates a +group over a directory on it, and invites a second person. It assumes you can +use a terminal. It assumes nothing else. + +For what each step *means* — and for everything this guide leaves out — read +[`USERGUIDE.md`](USERGUIDE.md). + +> **Scope.** Linux only: Ubuntu/Debian and Fedora. Windows is covered by +> [`PACKAGING-GUIDE.md`](PACKAGING-GUIDE.md) and is not repeated here. This +> guide uses **meshbay.org** as the hub; running your own is +> [`PACKAGING-GUIDE.md`](PACKAGING-GUIDE.md) plus [`HTTPS.md`](HTTPS.md) and +> [`MAIL-SERVER.md`](MAIL-SERVER.md). + +--- + +## What you are building + +``` + your machine meshbay.org your friend + ──────────── ─────────── ─────────── + meshbay-node ◄─── signalling ────► hub ◄─── sign-in ───► browser + holds the files accounts, or desktop + holds the group key group list, client + decides who is served introductions + │ │ + └──────────── encrypted, peer to peer, direct ──────────────────┘ + (your files never touch the hub) +``` + +Three things, and it is worth knowing which is which before you start: + +| | What it is | +|---|---| +| **The hub** | An address book and a switchboard. It holds your account and your group's name, and introduces two machines to each other. It never sees a file, a message or a key. | +| **The node** | A daemon on *your* machine. It holds the directories you share and the key that encrypts them. It decides who gets served. This is the part you install. | +| **The client** | The web app the hub serves, or the desktop application. This is what you and your members look at. | + +--- + +## Before you start + +- [ ] **A Linux machine that stays on.** Your files are served from it, so a + laptop that sleeps is a group that is offline half the time. A spare + mini-PC, a home server or an always-on desktop is the right shape. +- [ ] **A directory to share**, with something in it. +- [ ] **An email address** you can read — account sign-up sends a code to it. +- [ ] **About half an hour**, plus however long a first index takes — which + depends on how much you are sharing, and does not need watching. +- [ ] **Terminal access** to that machine. Everything below works over SSH; no + graphical session is needed on the node. + +You do **not** need a static IP, a domain name, port forwarding, or a router +you control. Two residential ISPs have been measured working without any of it. + +--- + +## Step 1 — Download the packages + +From **https://meshbay.org/downloads**, take the ones for your +distribution: + +| | Ubuntu / Debian | Fedora | +|---|---|---| +| **`meshbay-common`** — required, install it first | `.deb` | `.rpm` | +| **`meshbay-node`** — the daemon that hosts your files | `.deb` | `.rpm` | +| `meshbay-client` — the desktop application, optional | `.deb` | `.rpm` | + +You need the first two. The desktop application is worth having if this machine +has a screen, but nothing in this guide requires it: a terminal and a browser +are enough. + +Put them in one directory — the next step installs them together. + +--- + +## Step 2 — Install + +Install **with your package manager, not with `dpkg -i` / `rpm -ivh`**. Both of +those ignore weak dependencies, and the video drivers that let this machine +re-encode a film without melting are weak dependencies. + +```bash +cd ~/Downloads # wherever you put them + +# Ubuntu / Debian +sudo apt install ./meshbay-common_*.deb ./meshbay-node_*.deb + +# Fedora +sudo dnf install ./meshbay-common-*.rpm ./meshbay-node-*.rpm +``` + +Add `./meshbay-client_*` to that line to install the desktop application too. + +`meshbay-common` carries everything the others need, so there is nothing else +to install and no Python environment to set up. **ffmpeg**, required for video +streaming, comes in as a recommended dependency of the command above; without +it the node refuses to start and says so. + +Check it landed: + +```bash +meshbay-node status +``` + +It will report that there is no keystore. That is the next step. + +--- + +## Step 3 — Create your account + +Open **https://meshbay.org** in a browser and register. + +Three things on that page are worth slowing down for: + +1. **Your passphrase is not a password.** It never reaches the hub. It + encrypts the copy of your identity keys that lives on every node you join, + and nobody — not the hub, not an operator, not us — can reset it. The floor + is 12 characters; **four unrelated words** is the shape that actually works. +2. **Your recovery key is shown exactly once.** It is a 32-byte secret that can + restore your access to your groups if you forget the passphrase. Put it in a + password manager before clicking past it. Lose both it and the passphrase and + your files are still there — but every group has to be rejoined by hand, with + a new identity. +3. **Verify your email.** A code arrives; the account is inactive until you + enter it. + +--- + +## Step 4 — Set up the node + +Back on the node machine: + +```bash +meshbay-node init +``` + +It asks for the hub URL (press Enter for `https://meshbay.org`) and your hub +username. Then it writes `~/.config/meshbay/node.toml`, creates the keystore, +and prints something like: + +``` +Node key: 7mK2p...base64...= +``` + +**Copy that key.** In your browser, on meshbay.org: **Settings → Link Node**, +paste it, submit. + +This is what lets the hub introduce your members to this machine. It is a +public key; it identifies the node and unlocks nothing. + +--- + +## Step 5 — Start the node + +```bash +systemctl --user enable --now meshbay-node +loginctl enable-linger $USER # keep serving when you are not logged in +``` + +`enable-linger` is not optional on a machine you reach over SSH. Without it, +systemd stops your user services when your session ends — the group goes dark +the moment you disconnect. + +Check: + +```bash +meshbay-node status +``` + +You want to see `daemon running`. If not: + +```bash +journalctl --user -u meshbay-node -f +``` + +### If your files live outside your home directory + +The node unit is hardened: it can only write inside `~/.config/meshbay` and +`~/.local/share/meshbay`. An external drive or a second partition needs a +drop-in, and it needs **both** lines: + +```bash +mkdir -p ~/.config/systemd/user/meshbay-node.service.d +cat > ~/.config/systemd/user/meshbay-node.service.d/paths.conf <<'EOF' +[Service] +ReadWritePaths=/mnt/library +RequiresMountsFor=/mnt/library +EOF +systemctl --user daemon-reload +systemctl --user restart meshbay-node +``` + +`RequiresMountsFor` matters as much as `ReadWritePaths`. The service runs in its +own mount namespace, so a volume mounted *after* it started is invisible to it — +and the symptom is a directory that reads as empty while everything else looks +correct. + +--- + +## Step 6 — Create the group + +In the browser, on meshbay.org: **Create group** in the sidebar. + +- **Name** — anything. It is shown to members as `name@yourusername`. +- **Join policy** — leave it on **Invite only**. The alternative, *Open*, lists + the group publicly and lets anyone in, including the hub. There are groups + that want that; a first one is not it. +- **Description** — optional, shown to members on their home page. + +The group now exists on the hub and has no files, no key and no host. The next +step is all three. + +--- + +## Step 7 — Hand the group to your node + +Back on the node machine. Use the same name you just typed: + +```bash +meshbay-node group add "Family Photos" --dir ~/Pictures/shared +meshbay-node reload +meshbay-node gek init --group "Family Photos" +``` + +What those three did: + +| | | +|---|---| +| `group add` | told the node to host that group, and made the directory its first shared folder. It is **read-write** by default, so members can upload into it. Add `--no-writable` if you want a published, read-only library. | +| `reload` | made the running daemon re-read its config without dropping anyone. | +| `gek init` | generated the group's encryption key. **Nothing works before this** — the key never leaves your node, and every member receives it wrapped for their own key, on every connection. | + +The node starts indexing immediately. A large library takes a while; you can +watch it with `meshbay-node status` or in the group page, which shows the +progress. + +Want more than one directory in the group? + +```bash +meshbay-node root add /mnt/library/films --name Films +meshbay-node root add /mnt/usb/archive --removable # external drive +meshbay-node root list +``` + +Roots added later are **read-only by default** — the opposite of the first one, +deliberately. Pass `--writable` if members should be able to upload there. + +--- + +## Step 8 — Pair your browser + +Your node does not take orders from the hub. Before your browser can invite +anyone or delete a file, the node has to recognise it: + +```bash +meshbay-node operator pair +``` + +It prints a code like `R3H8-TB6V`, valid 24 hours. In the browser, open your +group → **Members** tab → enter the code. + +The code never passes through the hub. That is the whole point of it: a hub +that could name your operator key could make itself your node's administrator. + +--- + +## Step 9 — Let people reach you + +WebRTC picks a fresh UDP port per connection, so there is no single port to +forward. What the node needs is to **accept unsolicited inbound UDP on your +LAN** — browsers announce themselves with an address the node cannot resolve, +so the browser must be able to call the node, not the reverse. + +```bash +# Ubuntu — your LAN, never "anywhere" +sudo ufw allow from 192.168.0.0/16 app "MeshBay Node" + +# Fedora — apply to the zone holding your LAN interface +sudo firewall-cmd --permanent --zone=FedoraWorkstation --add-service=meshbay-node +sudo firewall-cmd --reload +``` + +**Scope it to the LAN.** This profile opens UDP 1024-65535; it does not belong +in an internet-facing zone. Members outside your network are reached by hole +punching, which needs no open port at all. + +The node's own admin surface is not affected: it listens on loopback only, +behind a token, and is never network-exposed. + +--- + +## Step 10 — Invite someone + +Your friend needs a meshbay.org account first — send them to Step 3. Then, with +their username: + +```bash +meshbay-node member invite alice_dupont +``` + +You get: + +``` +INVITATION CODE K7P2-9WQX +valid until 2026-09-25T17:40:00Z +``` + +Send that code however you normally talk to them — message, mail, out loud. It +works once, for that account only, for that group only, and the hub never sees +it. You do not need to be online when they use it. + +You can do the same thing from the **Members** tab of the group, from the +browser you paired in Step 8. + +--- + +## Step 11 — What your friend does + +1. Signs in at **https://meshbay.org**. +2. The group is already in their sidebar — creating the invitation registered + their membership. +3. They open it and are asked: *"This node needs to recognise you."* They paste + the code. +4. That is it. Your node pins their key, wraps the group key for it, and their + files appear. + +They will not be asked again on that browser. A *different* browser on the same +node recovers the same identity with their passphrase alone. A different +*node* — someone else's group — asks for a code again, as first contact always +does. + +--- + +## Did it work? + +```bash +meshbay-node status +``` + +A healthy node reads roughly like this: + +``` +hub https://meshbay.org (user yourname) +node key 7mK2p...= +daemon running — ok +node_id 82.65.x.x:0 +groups 1 files 4213 peers 1 +config /home/you/.config/meshbay/node.toml + group Family Photos [private] 8f3c... + shared → /home/you/Pictures/shared (rw) +operator yourname key AAAC3NzaC1lZDI1… paired 2026-09-18T14:02:11Z +``` + +If a line is missing, `status` names the command that fixes it. The four that +catch most people: + +| Symptom | Cause | +|---|---| +| `daemon not running` | Step 5, or a startup error in `journalctl --user -u meshbay-node` | +| `operator NONE PAIRED` | Step 8 — invites and file deletion are refused until this is done | +| an `action needed:` block naming a group key | Step 7's `gek init` was skipped — `meshbay-node group list` shows it as `NO KEY` | +| Group shows files to you, nothing to a member | The member never redeemed a code, or the firewall in Step 9 | + +--- + +## Where to go next + +- **Point Videos, Music and Photos at their folders.** Group → Settings — as + many folders as each library needs. Until you do, those tabs stay empty and + say so. +- **Turn off the applications you do not want.** Group → Members → Applications. + Files and Settings always stay. +- **Add your other devices.** Your phone's browser, the desktop application: + each one asks to be recognised, and you approve it from a device already + linked. Nobody else is involved. +- **Read [`USERGUIDE.md`](USERGUIDE.md)** — what each application does, how + members are managed, what happens when someone leaves, what is private and + what is not, and what to do when something breaks. |