Add vibe-kanban
This commit is contained in:
283
docs/INSTALL_VIBE_KANBAN_AND_DEV_MANAGER.md
Normal file
283
docs/INSTALL_VIBE_KANBAN_AND_DEV_MANAGER.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user