bmc_hub/DEVELOPMENT.md

BMC Hub - Development Guide

🚀 Quick Start

1. Clone & Setup

cd /Users/christianthomas/DEV/bmc_hub_dev
cp .env.example .env

2. Start Development Server

docker-compose up -d
docker-compose logs -f

3. Verify Installation

# 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

-- 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

# app/models/schemas.py
class ServiceBase(BaseModel):
    name: str
    customer_id: int

class Service(ServiceBase):
    id: int

3. Router

# 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

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

Database Queries

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

from app.core.config import settings

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

🐳 Docker Commands

# 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

cd /opt
git clone git@g.bmcnetworks.dk:ct/bmc_hub.git
cd bmc_hub

2. Configure Environment

cp .env.prod.example .env
nano .env  # Set RELEASE_VERSION, credentials, etc.

3. Deploy

docker-compose -f docker-compose.prod.yml up -d --build

4. Update to New Version

# 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

# 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

# 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

# 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

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

Release

# 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

lsof -i :8000
kill -9 <PID>

Database Connection Error

docker-compose logs postgres
docker-compose restart postgres

Clear Everything

docker-compose down -v  # WARNING: Deletes database!
docker-compose up -d

📞 Support

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