170 lines
5.3 KiB
Markdown
170 lines
5.3 KiB
Markdown
---
|
|
name: buzz-development
|
|
description: Buzz development environment setup, maintenance, and BrowserMCP
|
|
metadata:
|
|
author: dmgnr
|
|
version: 1.0.0
|
|
---
|
|
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
bun ds
|
|
```
|
|
|
|
Short for "docker exec -it app bun". Run one-off commands inside the app container:
|
|
|
|
```bash
|
|
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 | `[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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
docker compose -f dev/compose.yml restart app
|
|
docker compose -f dev/compose.yml restart backend
|
|
```
|
|
|
|
### Applying linting and formatting
|
|
|
|
```bash
|
|
bun lint # biome check --fix
|
|
bun format # biome format --write
|
|
```
|
|
|
|
### Running Drizzle Studio
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
1. The agent will ask you: _"Do you want to set up BrowserMCP for automated browser testing?"_
|
|
2. If you agree, the agent will:
|
|
|
|
a. Install the BrowserMCP package:
|
|
|
|
```bash
|
|
bun add -d @anthropic/browser-use
|
|
```
|
|
|
|
b. Add the MCP server configuration to `opencode.json` (or create/edit `.opencode.jsonc`):
|
|
|
|
```jsonc
|
|
{
|
|
"mcpServers": {
|
|
"browser": {
|
|
"command": "bunx",
|
|
"args": ["@anthropic/browser-use"],
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
c. Launch the browser and connect to `http://localhost:3000`
|
|
|
|
3. 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.
|