forked from cardosofelipe/fast-next-template
Felipe Cardoso
2310c8cdfd
- Add MCP server skeleton implementations for all 7 planned servers (llm-gateway, knowledge-base, git, issues, filesystem, code-analysis, cicd) - Add comprehensive DEVELOPMENT.md with setup and usage instructions - Add BACKLOG.md with detailed phase planning - Update docker-compose.dev.yml with Redis and Celery workers - Update CLAUDE.md with Syndarix-specific context Addresses issues #16, #20, #21 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
378 lines
9.1 KiB
Markdown
378 lines
9.1 KiB
Markdown
# Syndarix Development Environment
|
|
|
|
This guide covers setting up and running the Syndarix development environment.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker & Docker Compose v2+
|
|
- Python 3.12+
|
|
- Node.js 20+
|
|
- uv (Python package manager)
|
|
- Git
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://gitea.pragmazest.com/cardosofelipe/syndarix.git
|
|
cd syndarix
|
|
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
|
|
# Start all services
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ Docker Compose Development │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ PostgreSQL│ │ Redis │ │ Backend │ │ Frontend │ │
|
|
│ │ (pgvector)│ │ │ │ (FastAPI)│ │ (Next.js) │ │
|
|
│ │ :5432 │ │ :6379 │ │ :8000 │ │ :3000 │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
|
│ │ │
|
|
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Celery Workers │ │
|
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
|
|
│ │ │ celery-agent│ │ celery-git │ │ celery-sync │ │ │
|
|
│ │ │ (4 workers)│ │ (2 workers)│ │ (2 workers)│ │ │
|
|
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
|
|
│ │ ┌─────────────┐ │ │
|
|
│ │ │ celery-beat │ (Scheduler) │ │
|
|
│ │ └─────────────┘ │ │
|
|
│ └─────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Services
|
|
|
|
### Core Services
|
|
|
|
| Service | Port | Description |
|
|
|---------|------|-------------|
|
|
| db | 5432 | PostgreSQL 17 with pgvector extension |
|
|
| redis | 6379 | Redis 7 for cache, pub/sub, Celery broker |
|
|
| backend | 8000 | FastAPI backend |
|
|
| frontend | 3000 | Next.js frontend |
|
|
|
|
### Celery Workers
|
|
|
|
| Worker | Queue | Concurrency | Purpose |
|
|
|--------|-------|-------------|---------|
|
|
| celery-agent | agent | 4 | Agent execution tasks |
|
|
| celery-git | git | 2 | Git operations |
|
|
| celery-sync | sync | 2 | Issue synchronization |
|
|
| celery-beat | - | 1 | Scheduled task scheduler |
|
|
|
|
## Environment Variables
|
|
|
|
Copy `.env.example` to `.env` and configure:
|
|
|
|
```bash
|
|
# Database
|
|
POSTGRES_USER=syndarix
|
|
POSTGRES_PASSWORD=your_secure_password
|
|
POSTGRES_DB=syndarix
|
|
DATABASE_URL=postgresql://syndarix:your_secure_password@db:5432/syndarix
|
|
|
|
# Redis
|
|
REDIS_URL=redis://redis:6379/0
|
|
|
|
# Security
|
|
SECRET_KEY=your_32_character_secret_key_here
|
|
|
|
# Frontend
|
|
NEXT_PUBLIC_API_URL=http://localhost:8000
|
|
|
|
# CORS
|
|
BACKEND_CORS_ORIGINS=["http://localhost:3000"]
|
|
```
|
|
|
|
## Development Commands
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
# Enter backend directory
|
|
cd backend
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Run tests
|
|
IS_TEST=True uv run pytest
|
|
|
|
# Run with coverage
|
|
IS_TEST=True uv run pytest --cov=app --cov-report=html
|
|
|
|
# Run linting
|
|
uv run ruff check .
|
|
|
|
# Run type checking
|
|
uv run mypy app
|
|
|
|
# Generate migration
|
|
python migrate.py auto "description"
|
|
|
|
# Apply migrations
|
|
python migrate.py upgrade
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
# Enter frontend directory
|
|
cd frontend
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run development server
|
|
npm run dev
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Run E2E tests
|
|
npm run test:e2e
|
|
|
|
# Generate API client from backend OpenAPI spec
|
|
npm run generate:api
|
|
|
|
# Type check
|
|
npm run type-check
|
|
```
|
|
|
|
### Docker Compose
|
|
|
|
```bash
|
|
# Start all services
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
|
|
# Start specific services
|
|
docker-compose -f docker-compose.dev.yml up -d db redis backend
|
|
|
|
# View logs
|
|
docker-compose -f docker-compose.dev.yml logs -f backend
|
|
|
|
# Rebuild after Dockerfile changes
|
|
docker-compose -f docker-compose.dev.yml build --no-cache backend
|
|
|
|
# Stop all services
|
|
docker-compose -f docker-compose.dev.yml down
|
|
|
|
# Stop and remove volumes (clean slate)
|
|
docker-compose -f docker-compose.dev.yml down -v
|
|
```
|
|
|
|
### Celery
|
|
|
|
```bash
|
|
# View Celery worker status
|
|
docker-compose exec celery-agent celery -A app.celery_app inspect active
|
|
|
|
# View scheduled tasks
|
|
docker-compose exec celery-beat celery -A app.celery_app inspect scheduled
|
|
|
|
# Purge all queues (caution!)
|
|
docker-compose exec celery-agent celery -A app.celery_app purge
|
|
```
|
|
|
|
## Database Setup
|
|
|
|
### Enable pgvector Extension
|
|
|
|
The pgvector extension is automatically available with the `pgvector/pgvector:pg17` image.
|
|
|
|
To enable it in your database:
|
|
|
|
```sql
|
|
CREATE EXTENSION IF NOT EXISTS vector;
|
|
```
|
|
|
|
This is typically done in an Alembic migration.
|
|
|
|
### Migrations
|
|
|
|
```bash
|
|
# Check current migration status
|
|
python migrate.py current
|
|
|
|
# Generate new migration
|
|
python migrate.py auto "Add agent tables"
|
|
|
|
# Apply migrations
|
|
python migrate.py upgrade
|
|
|
|
# Rollback one migration
|
|
python migrate.py downgrade -1
|
|
```
|
|
|
|
## MCP Servers (Phase 2+)
|
|
|
|
MCP servers are located in `mcp-servers/`. Each server is a FastMCP application.
|
|
|
|
| Server | Priority | Status |
|
|
|--------|----------|--------|
|
|
| llm-gateway | 1 | Skeleton |
|
|
| knowledge-base | 2 | Skeleton |
|
|
| git | 3 | Skeleton |
|
|
| issues | 4 | Skeleton |
|
|
| filesystem | 5 | Skeleton |
|
|
| code-analysis | 6 | Skeleton |
|
|
| cicd | 7 | Skeleton |
|
|
|
|
To run an MCP server locally:
|
|
|
|
```bash
|
|
cd mcp-servers/llm-gateway
|
|
uv sync
|
|
uv run python server.py
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Backend Tests
|
|
|
|
```bash
|
|
# Unit tests (uses SQLite in-memory)
|
|
IS_TEST=True uv run pytest
|
|
|
|
# E2E tests (requires Docker)
|
|
make test-e2e
|
|
|
|
# Run specific test file
|
|
IS_TEST=True uv run pytest tests/api/test_auth.py
|
|
|
|
# Run with verbose output
|
|
IS_TEST=True uv run pytest -v
|
|
```
|
|
|
|
### Frontend Tests
|
|
|
|
```bash
|
|
# Unit tests
|
|
npm test
|
|
|
|
# E2E tests (Playwright)
|
|
npm run test:e2e
|
|
|
|
# E2E with UI
|
|
npm run test:e2e:ui
|
|
|
|
# E2E debug mode
|
|
npm run test:e2e:debug
|
|
```
|
|
|
|
## Debugging
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
# View backend logs
|
|
docker-compose logs -f backend
|
|
|
|
# Access container shell
|
|
docker-compose exec backend bash
|
|
|
|
# Run Python REPL with app context
|
|
docker-compose exec backend python
|
|
>>> from app.core.config import settings
|
|
>>> print(settings.PROJECT_NAME)
|
|
```
|
|
|
|
### Database
|
|
|
|
```bash
|
|
# Connect to PostgreSQL
|
|
docker-compose exec db psql -U syndarix -d syndarix
|
|
|
|
# List tables
|
|
\dt
|
|
|
|
# Describe table
|
|
\d users
|
|
```
|
|
|
|
### Redis
|
|
|
|
```bash
|
|
# Connect to Redis CLI
|
|
docker-compose exec redis redis-cli
|
|
|
|
# List all keys
|
|
KEYS *
|
|
|
|
# Check pub/sub channels
|
|
PUBSUB CHANNELS *
|
|
```
|
|
|
|
## Common Issues
|
|
|
|
### "Port already in use"
|
|
|
|
Stop conflicting services or change ports in docker-compose.dev.yml.
|
|
|
|
### "Database connection refused"
|
|
|
|
Wait for PostgreSQL healthcheck to pass:
|
|
```bash
|
|
docker-compose logs db | grep "ready to accept connections"
|
|
```
|
|
|
|
### "Import error" for new dependencies
|
|
|
|
Rebuild the container:
|
|
```bash
|
|
docker-compose build --no-cache backend
|
|
```
|
|
|
|
### Migrations out of sync
|
|
|
|
```bash
|
|
# Check current state
|
|
python migrate.py current
|
|
|
|
# If needed, stamp current revision
|
|
python migrate.py stamp head
|
|
```
|
|
|
|
## IDE Setup
|
|
|
|
### VS Code
|
|
|
|
Recommended extensions:
|
|
- Python
|
|
- Pylance
|
|
- Ruff
|
|
- ESLint
|
|
- Prettier
|
|
- Docker
|
|
- GitLens
|
|
|
|
### PyCharm
|
|
|
|
1. Set Python interpreter to uv's .venv
|
|
2. Enable Ruff integration
|
|
3. Configure pytest as test runner
|
|
|
|
## Next Steps
|
|
|
|
1. Set up your `.env` file with appropriate values
|
|
2. Start the development environment: `docker-compose -f docker-compose.dev.yml up -d`
|
|
3. Run migrations: `cd backend && python migrate.py upgrade`
|
|
4. Access the frontend at http://localhost:3000
|
|
5. Access the API docs at http://localhost:8000/docs
|
|
|
|
For architecture details, see [ARCHITECTURE.md](./architecture/ARCHITECTURE.md).
|