Quickstart¶

From zero to a running two-browser meeting in about five minutes.

Prerequisites¶

Go 1.24+ (to build the pinned upstream Galene)
Python 3.12+ and uv
Node.js 20+
honcho (uv tool install honcho)
Docker is optional — for Postgres; SQLite is the default

One-time setup¶

git clone <this repo> beep && cd beep
make build          # builds upstream Galene, syncs the backend, npm install
make dev-config     # creates dirs and runs alembic upgrade head

make build clones upstream Galene at the pinned ref into vendor/galene/ and compiles it, uv syncs the backend, and runs npm install in the frontend.

Why the migration step matters

The backend runs with create_all=False, so a fresh checkout has no schema until Alembic has run. make dev-config does it, and every make run / make e2e-* target depends on it.

Run the dev stack¶

make run

honcho starts three processes:

Process	Port	What
`sfu.1`	`:8443`	upstream Galene, plain HTTP (insecure dev mode)
`backend.1`	`:8000`	Litestar backend
`front.1`	`:5173`	Vite dev server

Open http://localhost:5173, click New meeting, fill in a name. Open a second private window on the same URL to see two participants.

Why the browser connects through :5173

Vite proxies /ws to the SFU so the WebSocket upgrade is same-origin. Galene rejects a cross-origin upgrade with 403 unless allowOrigin names the page — see SFU.

make run-alt        # same frontend and SFU, aiohttp alt-backend instead

Run the test suites¶

make test           # backend + front
make test-backend   # pytest
make test-front     # Vitest

Run the e2e suites¶

These boot the full stack, run Playwright, and tear down.

make e2e-all        # against the Litestar backend  (3 specs)
make e2e-alt        # against the alt-backend       (2 specs)

e2e-alt runs only the guest specs: the alt-backend has no auth and no admin surface, so the admin spec doesn't apply to it.

Postgres instead of SQLite¶

make compose-up
export DATABASE_URL=postgresql+asyncpg://beep:beep@localhost:5432/beep
cd backend && uv run alembic upgrade head && cd ..
make run

Port 5432 collides

If you have a local PostgreSQL bound to 127.0.0.1:5432, it wins over the container for localhost connections, and alembic fails with role "beep" does not exist while docker exec … pg_isready reports healthy. Map the container to a free port, or stop the local server.

Run the production stack locally (Docker)¶

cp deploy/.env.production.example .env.production

mkdir -p deploy/galene/groups deploy/galene/data
# see deploy/galene/README.md for generating the signing key

Then local-only overrides so Caddy doesn't need ports 80/443:

cat >> .env.production <<'ENVEOF'
MEET_DOMAIN=:80
HOST_HTTP_PORT=8080
HOST_HTTPS_PORT=8443
ENVEOF

make prod-up
curl -s http://localhost:8080/api/v1/config

First build takes a few minutes. make prod-down tears it down and preserves the Postgres volume. See Deployment.

Troubleshooting¶

Port already in use — lsof -i:8443 -sTCP:LISTEN and kill strays on :8000, :8443, :5173.

Failed to spawn: alembic — the virtualenv is stale, usually because the directory was moved (virtualenvs hard-code absolute paths). cd backend && rm -rf .venv && uv sync.

Playwright can't find a browser — cd front && npx playwright install chromium. If it reports success but the executable is still missing, the cache entry is corrupt: delete ~/Library/Caches/ms-playwright/chromium*-<build> and reinstall.

403 on the WebSocket upgrade — the page's origin isn't allowed. In dev, connect through the Vite proxy; in production, set allowOrigin.