5.3 KiB
name, description, metadata
| name | description | metadata | ||||
|---|---|---|---|---|---|---|
| buzz-development | Buzz development environment setup, maintenance, and BrowserMCP |
|
Buzz — Development Environment & Maintenance
This skill covers the local dev environment, common maintenance tasks, and BrowserMCP setup.
Prerequisites
- Bun (matching the project's Bun version in Docker)
- Docker with Compose Watch support
- Environment file at
dev/.env.development
Dev Environment
Starting development
bun dev
This runs docker compose up --watch from dev/compose.yml, spinning up:
| Container | Purpose | Notes |
|---|---|---|
app |
Next.js dev server (port 3000) | File sync via Docker watch, autoreloads |
backend |
Background worker (card caching, cron, webhooks) | Rebuilds on backend/ changes |
db |
PostgreSQL (port 5432) | Auto-creates on first run |
redis |
Redis (port 6379) | Pub-sub for SSE, persistence enabled |
redis-commander |
Redis GUI (port 6380) | Optional, for debugging |
drizzle |
Drizzle Studio (port 4983) | DB management UI |
The bun dev command runs foreground only. Press Ctrl+C to stop all containers.
Attaching to the app container
bun ds
Short for "docker exec -it app bun". Run one-off commands inside the app container:
bun ds bun nextdev # start next dev manually
bun ds bun dr push # push schema to dev database
bun ds bun dr studio # start drizzle studio
bun ds bun lint # lint inside container
Default dev credentials
Seeded automatically by the backend on first startup when ENVIRONMENT=development:
| Field | Value |
|---|---|
[email protected] |
|
| Password | youshallnotpass |
| Role | admin |
Seeding is idempotent — it skips if an admin account already exists.
Command Reference
| Command | What it does |
|---|---|
bun dev |
Start all dev containers with file watch |
bun ds <cmd> |
Run a command in the app container |
bun nextdev |
Start Next.js dev server directly (outside Docker) |
bun build |
Build for production (Turbopack) |
bun start |
Start production server |
bun lint |
Run Biome check with auto-fix |
bun format |
Run Biome formatter |
bun dr <args> |
Run drizzle-kit commands |
bun logs |
Tail logs from all containers (docker compose logs -fn50) |
bun test |
Run Playwright tests (outdated — unreliable) |
Common Maintenance Tasks
Checking logs
bun logs # all services
docker compose -f dev/compose.yml logs -fn50 app # just the app
docker compose -f dev/compose.yml logs -fn50 backend
Restarting a service
docker compose -f dev/compose.yml restart app
docker compose -f dev/compose.yml restart backend
Applying linting and formatting
bun lint # biome check --fix
bun format # biome format --write
Running Drizzle Studio
bun ds bun dr studio --host $(hostname) # via container
Then visit http://localhost:4983.
Database migrations
See the buzz-database skill for the full workflow.
Updating dependencies
bun ds bun install <package>
After adding new deps, you may need to rebuild the Docker images.
BrowserMCP Setup
Before doing any UI/interaction work, you must set up BrowserMCP for automated browser testing.
Flow
-
The agent will ask you: "Do you want to set up BrowserMCP for automated browser testing?"
-
If you agree, the agent will:
a. Install the BrowserMCP package:
bun add -d @anthropic/browser-useb. Add the MCP server configuration to
opencode.json(or create/edit.opencode.jsonc):{ "mcpServers": { "browser": { "command": "bunx", "args": ["@anthropic/browser-use"], }, }, }c. Launch the browser and connect to
http://localhost:3000 -
The agent will then perform browser-based testing/verification using the MCP browser tools.
When to use BrowserMCP
- Verifying UI changes after implementing a feature
- Testing form submissions, login flows, or admin interactions
- Checking that SSE live updates work correctly
- Validating responsive layout and navigation
Important
- Do not run Playwright tests — they are heavily outdated and unreliable.
- Always use BrowserMCP for visual/interaction verification instead.
- The dev server must already be running for BrowserMCP to connect.