bmc_hub/DEVELOPMENT.md

# BMC Hub - Development Guide

## 🚀 Quick Start

### 1. Clone & Setup
```bash
cd /Users/christianthomas/DEV/bmc_hub_dev
cp .env.example .env
```

### 2. Start Development Server
```bash
docker-compose up -d
docker-compose logs -f
```

### 3. Verify Installation
```bash
# Health check
curl http://localhost:8000/health

# API docs
open http://localhost:8000/api/docs

# Dashboard
open http://localhost:8000
```

## 📁 Project Structure

```
bmc_hub/
├── app/
│   ├── core/          # Config & database
│   ├── models/        # Pydantic schemas
│   ├── routers/       # API endpoints
│   ├── services/      # Business logic
│   └── jobs/          # Scheduled tasks
├── migrations/        # Database migrations
├── static/           # Web UI
├── .env.example      # Local dev template
└── .env.prod.example # Production template
```

## 🔧 Development Workflow

### Adding a New Feature

1. **Database Migration**
```sql
-- migrations/002_add_services.sql
CREATE TABLE services (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    customer_id INTEGER REFERENCES customers(id)
);
```

2. **Pydantic Models**
```python
# app/models/schemas.py
class ServiceBase(BaseModel):
    name: str
    customer_id: int

class Service(ServiceBase):
    id: int
```

3. **Router**
```python
# app/routers/services.py
from fastapi import APIRouter
router = APIRouter()

@router.get("/services")
async def list_services():
    return execute_query("SELECT * FROM services")
```

4. **Register Router**
```python
# main.py
from app.routers import services
app.include_router(services.router, prefix="/api/v1", tags=["Services"])
```

### Database Queries
```python
from app.core.database import execute_query

# Fetch
customers = execute_query("SELECT * FROM customers WHERE id = %s", (id,))

# Insert
result = execute_query(
    "INSERT INTO customers (name) VALUES (%s) RETURNING *",
    (name,)
)
```

### Configuration
```python
from app.core.config import settings

if settings.ECONOMIC_READ_ONLY:
    logger.warning("Read-only mode")
```

## 🐳 Docker Commands

```bash
# Start
docker-compose up -d

# Logs
docker-compose logs -f api

# Restart
docker-compose restart api

# Stop
docker-compose down

# Rebuild
docker-compose up -d --build
```

## 🚢 Production Deployment

### On Live Server

1. **Clone & Setup**
```bash
cd /opt
git clone git@g.bmcnetworks.dk:ct/bmc_hub.git
cd bmc_hub
```

2. **Configure Environment**
```bash
cp .env.prod.example .env
nano .env  # Set RELEASE_VERSION, credentials, etc.
```

3. **Deploy**
```bash
docker-compose -f docker-compose.prod.yml up -d --build
```

4. **Update to New Version**
```bash
# Update .env with new RELEASE_VERSION
nano .env  # Change to v1.2.3

# Pull and restart
docker-compose -f docker-compose.prod.yml up -d --build
```

## 📊 Monitoring

### Health Checks
```bash
# Simple
curl http://localhost:8000/health

# Detailed
curl http://localhost:8000/api/v1/system/health

# Config
curl http://localhost:8000/api/v1/system/config
```

### Logs
```bash
# Application logs
tail -f logs/app.log

# Docker logs
docker-compose logs -f api
```

## 🔐 Security Checklist

### Before Production
- [ ] Change `SECRET_KEY` to random value
- [ ] Set strong `POSTGRES_PASSWORD`
- [ ] Set `ECONOMIC_READ_ONLY=true`
- [ ] Set `ECONOMIC_DRY_RUN=true`
- [ ] Use tagged release version (not `latest`)
- [ ] Configure proper CORS origins
- [ ] Setup Nginx reverse proxy
- [ ] Enable SSL/TLS

## 🧪 Testing

```bash
# Install test dependencies
pip install pytest pytest-cov

# Run tests
pytest

# With coverage
pytest --cov=app --cov-report=html
open htmlcov/index.html
```

## 📝 Git Workflow

### Development
```bash
git checkout -b feature/new-feature
# Make changes
git add .
git commit -m "Add new feature"
git push origin feature/new-feature
```

### Release
```bash
# Tag release
git tag v1.2.3
git push --tags

# Update production .env with RELEASE_VERSION=v1.2.3
```

## 🔗 Links

- **API Docs**: http://localhost:8000/api/docs
- **ReDoc**: http://localhost:8000/api/redoc
- **Dashboard**: http://localhost:8000
- **Gitea**: https://g.bmcnetworks.dk/ct/bmc_hub

## 🆘 Troubleshooting

### Port Already in Use
```bash
lsof -i :8000
kill -9 <PID>
```

### Database Connection Error
```bash
docker-compose logs postgres
docker-compose restart postgres
```

### Clear Everything
```bash
docker-compose down -v  # WARNING: Deletes database!
docker-compose up -d
```

## 📞 Support

- Issues: Gitea Issues
- Email: support@bmcnetworks.dk