284 lines
6.6 KiB
Markdown
284 lines
6.6 KiB
Markdown
# Installation Guide: Vibe Kanban & dev-manager-mcp
|
|
|
|
This guide will help you install and configure Vibe Kanban and dev-manager-mcp for managing your development workflow with isolated test environments.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js >= 18 (or Bun)
|
|
- Docker installed and running
|
|
- PostgreSQL client (psql) installed
|
|
- Main database running on localhost:5432
|
|
|
|
## Part 1: Install dev-manager-mcp
|
|
|
|
dev-manager-mcp is a daemon that manages multiple dev servers in parallel, allocating unique ports to avoid collisions.
|
|
|
|
### Installation
|
|
|
|
**Option 1: Use via npx (Recommended - No Installation Needed)**
|
|
|
|
No installation required! Just use `npx`:
|
|
|
|
```bash
|
|
# Start the daemon
|
|
npx -y dev-manager-mcp daemon
|
|
```
|
|
|
|
**Option 2: Install Globally**
|
|
|
|
```bash
|
|
npm install -g dev-manager-mcp
|
|
# or
|
|
bun install -g dev-manager-mcp
|
|
```
|
|
|
|
### Start the Daemon
|
|
|
|
Open a terminal and keep it running:
|
|
|
|
```bash
|
|
npx -y dev-manager-mcp daemon
|
|
```
|
|
|
|
You should see output indicating the daemon is running. Keep this terminal open.
|
|
|
|
### Verify Installation
|
|
|
|
In another terminal, test the MCP connection:
|
|
|
|
```bash
|
|
# Check if daemon is accessible
|
|
npx dev-manager-mcp status
|
|
```
|
|
|
|
## Part 2: Install Vibe Kanban
|
|
|
|
Vibe Kanban is a task management system that integrates with coding agents and can automatically start dev environments.
|
|
|
|
### Installation
|
|
|
|
**Option 1: Use via npx (Recommended - No Installation Needed)**
|
|
|
|
```bash
|
|
# Just run it - no installation needed
|
|
npx vibe-kanban
|
|
```
|
|
|
|
**Option 2: Install Globally**
|
|
|
|
```bash
|
|
npm install -g vibe-kanban
|
|
# or
|
|
bun install -g vibe-kanban
|
|
```
|
|
|
|
### First Run
|
|
|
|
1. **Start Vibe Kanban:**
|
|
|
|
```bash
|
|
npx vibe-kanban
|
|
```
|
|
|
|
2. **Authenticate with your coding agent:**
|
|
- Vibe Kanban will prompt you to authenticate
|
|
- Follow the instructions for your agent (Claude, Codex, etc.)
|
|
|
|
3. **Access the UI:**
|
|
- Vibe Kanban will start a web server
|
|
- Open the URL shown in the terminal (usually http://localhost:3000)
|
|
|
|
### Configure MCP Integration
|
|
|
|
1. **Open Vibe Kanban Settings:**
|
|
- In the Vibe Kanban UI, go to Settings
|
|
- Find "MCP Servers" or "Agent Configuration"
|
|
|
|
2. **Add dev-manager-mcp:**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"dev-manager": {
|
|
"command": "npx",
|
|
"args": ["dev-manager-mcp", "stdio"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
3. **Configure QA Automation:**
|
|
- In Settings, find "QA" or "Testing" section
|
|
- Enable "Auto-start dev environments"
|
|
- Set script path: `scripts/start-task-docker.sh`
|
|
- Set health check URL: `http://localhost:{port}/health`
|
|
|
|
## Part 3: Configure for Your Project
|
|
|
|
### Create Vibe Kanban Configuration
|
|
|
|
**Recommended: At Projects level** (to manage all projects):
|
|
|
|
Create a `.vibe-kanban` directory in your Projects folder:
|
|
|
|
```bash
|
|
cd /Users/oda/Desktop/Projects
|
|
mkdir -p .vibe-kanban
|
|
```
|
|
|
|
Create `/Users/oda/Desktop/Projects/.vibe-kanban/config.json`:
|
|
|
|
```json
|
|
{
|
|
"projectRoot": "/Users/oda/Desktop/Projects",
|
|
"mcpServers": {
|
|
"dev-manager": {
|
|
"command": "npx",
|
|
"args": ["dev-manager-mcp", "stdio"]
|
|
}
|
|
},
|
|
"qa": {
|
|
"enabled": true,
|
|
"autoStartDevEnv": true,
|
|
"devEnvScript": "managing-apps/scripts/start-task-docker.sh",
|
|
"healthCheckUrl": "http://localhost:{port}/health",
|
|
"dashboardUrl": "http://localhost:{port}"
|
|
},
|
|
"tasks": {
|
|
"statuses": {
|
|
"ready-for-qa": {
|
|
"autoStartDevEnv": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Note**: The `devEnvScript` path is relative to the Projects folder. For managing-apps, it's `managing-apps/scripts/start-task-docker.sh`. For other projects, configure project-specific scripts in Vibe Kanban's project settings.
|
|
|
|
### Update Your MCP Configuration
|
|
|
|
If you're using Cursor or another editor with MCP support, add to your MCP config (usually `~/.cursor/mcp.json` or similar):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"dev-manager": {
|
|
"command": "npx",
|
|
"args": ["dev-manager-mcp", "stdio"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Part 4: Usage Workflow
|
|
|
|
### For Development (Agent)
|
|
|
|
1. **Make code changes**
|
|
2. **Start test environment:**
|
|
```bash
|
|
cd /Users/oda/Desktop/Projects/managing-apps
|
|
bash scripts/start-dev-env.sh DEV-A3X9
|
|
```
|
|
3. **Test your changes** at the provided URLs
|
|
4. **Stop when done:**
|
|
```bash
|
|
bash scripts/stop-task-docker.sh DEV-A3X9
|
|
```
|
|
|
|
### For QA (Vibe Kanban)
|
|
|
|
1. **Move task to "Ready for QA" status**
|
|
2. **Vibe Kanban automatically:**
|
|
- Starts a Docker environment
|
|
- Copies the database
|
|
- Provides test URLs
|
|
3. **Test the task**
|
|
4. **Move to "Done" or "Needs Changes"**
|
|
5. **Vibe Kanban automatically stops the environment**
|
|
|
|
### Manual Management
|
|
|
|
**Start an environment:**
|
|
```bash
|
|
cd /Users/oda/Desktop/Projects/managing-apps
|
|
bash scripts/start-task-docker.sh TASK-123 0
|
|
```
|
|
|
|
**Check status:**
|
|
```bash
|
|
npx dev-manager-mcp status
|
|
```
|
|
|
|
**View logs:**
|
|
```bash
|
|
docker logs managing-api-TASK-123
|
|
```
|
|
|
|
**Stop an environment:**
|
|
```bash
|
|
bash scripts/stop-task-docker.sh TASK-123
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### dev-manager-mcp Issues
|
|
|
|
**Daemon not starting:**
|
|
- Check Node.js version: `node --version` (needs >= 18)
|
|
- Try: `npx -y dev-manager-mcp daemon --verbose`
|
|
|
|
**Cannot connect to daemon:**
|
|
- Make sure daemon is running in another terminal
|
|
- Check if port is already in use
|
|
- Restart the daemon
|
|
|
|
### Vibe Kanban Issues
|
|
|
|
**Cannot start:**
|
|
- Check Node.js version: `node --version` (needs >= 18)
|
|
- Try: `npx vibe-kanban --verbose`
|
|
|
|
**MCP not working:**
|
|
- Verify dev-manager-mcp daemon is running
|
|
- Check MCP configuration in Vibe Kanban settings
|
|
- Restart Vibe Kanban
|
|
|
|
**Auto-start not working:**
|
|
- Check script path in configuration
|
|
- Verify script is executable: `chmod +x scripts/start-task-docker.sh`
|
|
- Check Vibe Kanban logs
|
|
|
|
### Docker Issues
|
|
|
|
**Port conflicts:**
|
|
- Use different port offset: `bash scripts/start-task-docker.sh TASK-123 10`
|
|
- Check what's using ports: `lsof -i :5000`
|
|
|
|
**Database copy fails:**
|
|
- Verify main database is running: `docker ps | grep postgres`
|
|
- Check PostgreSQL client: `which psql`
|
|
- Verify connection: `PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d managing -c '\q'`
|
|
|
|
## Next Steps
|
|
|
|
1. ✅ Install dev-manager-mcp (via npx)
|
|
2. ✅ Install Vibe Kanban (via npx)
|
|
3. ✅ Start dev-manager-mcp daemon
|
|
4. ✅ Start Vibe Kanban
|
|
5. ✅ Configure MCP integration
|
|
6. ✅ Test with a sample task
|
|
|
|
## Resources
|
|
|
|
- [Vibe Kanban GitHub](https://github.com/BloopAI/vibe-kanban)
|
|
- [Vibe Kanban Documentation](https://www.vibekanban.com/vibe-guide)
|
|
- [dev-manager-mcp GitHub](https://github.com/BloopAI/dev-manager-mcp)
|
|
- [MCP Documentation](https://modelcontextprotocol.io/)
|
|
|
|
## Support
|
|
|
|
- Vibe Kanban: [GitHub Discussions](https://github.com/BloopAI/vibe-kanban/discussions)
|
|
- dev-manager-mcp: [GitHub Issues](https://github.com/BloopAI/dev-manager-mcp/issues)
|
|
|