Self-hosting onboarding is frustrating

[RavIndh11]

I spent some time trying to set up Buzz on a Ubuntu server on my LAN, and the onboarding experience and documentation currently make this very difficult.

The architecture is really interesting, but the current documentation assumes everything is being run on localhost with the Desktop App. Please consider adding a clear "Self-Hosting / LAN Setup" guide, documenting the required environment variables, and explaining the manual git setup for those who just want to use the CLI and a web browser.

[air3ijai]

Also would be curious to have a self-hosted instance detailed guide and there is a separate configuration for that - Buzz Docker Compose deployment.

In general it looks like following

1. Setup a relay with all services on a VPS and expose just a websocket endpoint
2. Run Desktop app and connect to that endpoint

Environment variables for relay could be seen in a deploy/compose/.env.example.

[Elshad]

I got below error:

elshad@main-ubuntu-001:~/buzz/deploy/compose$ ./run.sh start
[+] up 4/4
✔ Container buzz-prod-postgres-1 Running 0.0s
✔ Container buzz-prod-redis-1 Running 0.0s
✔ Container buzz-prod-relay-1 Recreated 0.1s
✘ Container buzz-prod-minio-1 Error dependency minio failed to start 0.5s
dependency failed to start: container buzz-prod-minio-1 is unhealthy

[air3ijai]

Check on a local VM using multipass

1. Run Ubuntu VM

   multipass launch -n buzz 24.04
   multipass shell buzz
   sudo -s

2. Install Docker

3. Get buzz repository

   cd /opt
   git clone --filter=blob:none --sparse https://github.com/block/buzz
   cd buzz
   git sparse-checkout add deploy/compose

4. Prepare config

   cd deploy/compose
   cp .env.example .env
   
   # we could use docker image for keys generation
   docker run --rm -it --entrypoint bash ghcr.io/block/buzz -c "buzz-admin generate-key"
   
   vi .env

5. Run Buzz

   ./run.sh start

6. Check status

   ./run.sh status

7. Check logs

   # Minio
   ./run.sh logs minio
   
   # All
   ./run.sh logs

8. Get relay node IP

   ip -brief address show

9. Connect from Buzz using ws://vm-ip:3000

---

You will get an error on connecting, but that is another story

relay returned 404 Not Found: relay: no community is configured for this host"

Performed experiment just shows that deployment on VM should work.

[Elshad]

@air3ijai thank you for answer.
Problem of minio was BUZZ_S3_SECRET_KEY length. I assigned 6 digit something, but have to be 8.
Now everything are healthy and runs.

My another problem I have not any device to run desktop app. Only iPhone. Hermes agent somehow generated to me key pair, it was valid. But I was unsuccess to use it

[air3ijai]

@Elshad, I was able to check mobile device, on block-hosted community, using the following steps

1. Connect to a workspace using Buzz Desktop
2. Open Profile --> Settings --> Mobile --> Pairing
3. Download and install Buzz on Mobile --> Android: https://play.google.com/store/apps/details?id=xyz.block.buzz.mobile
4. Open Buzz on Mobile and select Scan a QR code
5. You will see a security code on both ends - Desktop and Mobile
6. Press Code match on both ends - Desktop and Mobile
7. After that, Mobile will join workspace.

Also, we could find a tool buzz-pairing-cli, but most probably it is just to test pairing protocol and can't be used for joining.

[air3ijai]

We could find a confirmation in #2324, that at this moment, on-boarding is a Desktop-first

• we have to install and run Desktop
• only after that we can pair it with a Mobile

[air3ijai]

Also, PR #2361 contains a "Get Buzz on your phone" guide

get-buzz-on-your-phone.md

Get Buzz on your phone

Pair the Buzz mobile app with desktop so your identity and communities show up on your phone. Pairing copies your identity to a device you own. To onboard someone else, send them a community invite link instead.

Install the mobile app

Search your store for Buzz — chat with your hive:

• iOS: App Store
• Android: Google Play (xyz.block.buzz.mobile)

Update the desktop app before pairing so both sides speak the same protocol.

Pair with desktop

1. On desktop, open Settings (⌘, on Mac, or click your user icon in the bottom-left).
2. Open the Mobile tab and click Pair Mobile Device. A QR code appears: “Scan this QR code with the Buzz mobile app to securely pair.”
3. On your phone, open Buzz. On the welcome screen, tap Scan QR Code and point the camera at the desktop QR.
   • No camera handy? Use Copy pairing code on desktop and paste it on the phone.
4. A short security code appears on both screens. Confirm they match, then confirm on both devices. Only confirm a pairing you started yourself.
5. When you see “Your mobile device is now paired,” your identity and communities are on the phone.

Good to know

• Codes don’t match? Pairing cancels itself for security — start over from desktop.
• Pairing vs invite: pairing copies your existing identity to another of your devices. Use a community invite link when onboarding a teammate.
• Push notifications are supported on hosted communities.
• You can pair more than one phone; each device goes through the same flow.

For workplace rollouts

Hand teammates this page (or a printout) with:

1. Store install links / QR codes for iOS and Android
2. The six pairing steps above
3. The community invite link for people who don’t already have a Buzz identity

Admins: after someone joins on desktop, point them to Settings → Mobile → Pair Mobile Device.

[air3ijai]

We also have several PR's which states that mobile pairing is not working out of the box on a self-hosted relay

• fix(deploy): bundle buzz-pair-relay sidecar so mobile pairing works out of the box #2736
• fix(compose): restore mobile pairing sidecar #3627
• fix(compose): wire buzz-pair-relay so mobile QR pairing works #3875
• feat(deploy): add device-pairing sidecar to the compose stack #4656