Local Dev

This guide is for running BeeBuzz locally with the shortest practical setup.

It is intentionally focused on development, not production self-hosting.

Prerequisites

What This Uses

  • BeeBuzz server, site, and Hive — the core services
  • Caddy — reverse proxy
  • lancert.dev — local HTTPS certificates and subdomains
  • Mailpit — email capture
  • mise — task runner and tool manager

1. Clone The Repo

git clone https://codeberg.org/beebuzz/beebuzz.git
cd beebuzz

2. One-Time Setup

mise run setup

This installs tools and dependencies, creates .env from the template, generates VAPID keys, and prompts for a bootstrap admin email (defaults to admin@beebuzz.local).

3. Start The Full Dev Stack

mise run dev

mise run dev fails with a clear message if you skipped setup.

On first run it:

  • detects your LAN IP
  • derives a *.lancert.dev domain (e.g. 192-168-1-42.lancert.dev)
  • offers to update BEEBUZZ_DOMAIN in .env
  • fetches TLS certificates if needed

The stack includes:

  • site
  • Hive
  • API
  • Caddy
  • Mailpit

4. Open The Local Apps

Once the stack is up, use these URLs:

  • site: https://$BEEBUZZ_DOMAIN
  • Hive: https://hive.$BEEBUZZ_DOMAIN
  • API: https://api.$BEEBUZZ_DOMAIN
  • Mailpit: http://localhost:8025

5. Sign In

Open the site and request access with the bootstrap email you configured.

The OTP email lands in Mailpit, so you can complete sign-in locally without external email infrastructure.

6. Pair A Device

Open Account -> Devices and click Add Device.

Then:

  1. open Hive from the generated link or QR code
  2. install the PWA if prompted
  3. grant notification permission
  4. enter the pairing code

For the smoothest results, pair on the same machine first, then test on additional devices if needed.

7. Create A Token

Open Account -> API Tokens and create a token for the topic you want to use.

Copy the token immediately.

8. Connect The CLI

beebuzz connect --api-url "https://api.$BEEBUZZ_DOMAIN"

Paste the token when prompted.

9. Send A Test Message

beebuzz send "Local dev works"

If the device is paired and permissions are still valid, the notification should arrive right away.

Notes

  • This flow is for local development only.
  • It is the recommended way to validate the full BeeBuzz loop quickly during beta.
  • Detailed production deployment docs will come later, once the self-host path is ready to support properly.