Coblyn Development Guide

⏱ 20 minNivel · Contribuidorv1.16.0

For Developers: How to work with the Coblyn codebase effectively

Prerequisites

Before starting development on Coblyn:

Read the Architecture: /architecture/coblyn-system
Review the technical Knowledge Base: coblyn/docs/KNOWLEDGE-BASE.md
Understand the Skill: The coblyn-pxe-system skill contains all critical patterns

Development Environment Setup

1. Clone and Navigate

bash

git clone https://github.com/cpita1980/Coblyn.git
cd Coblyn/coblyn

2. Configure Environment

bash

cp .env.example .env
nano .env  # Configure your network settings

3. Run Setup Script

bash

bash setup.sh

This script will:

Validate Docker installation
Create necessary directories
Set up initial configuration
Download PXE boot files

4. Start Development Environment

bash

docker compose up -d

Project Structure

coblyn/
├── docker/                # Container definitions
│   ├── kea/              # ISC Kea DHCP
│   ├── tftp/             # tftpd-hpa
│   ├── backend/          # FastAPI
│   └── frontend/         # React + Vite
├── web/
│   ├── backend/          # FastAPI application
│   │   ├── main.py       # App entry, lifespan, migrations
│   │   ├── models.py     # SQLAlchemy 2.0 models
│   │   ├── routers/      # API endpoints
│   │   └── utils/        # kea_client, nfs_manager, wol, oui_lookup
│   └── frontend/         # React application
│       └── src/
│           ├── pages/    # Page components
│           ├── i18n/     # Translations (ES/EN)
│           └── lib/      # API client, utilities
├── tftpboot/             # PXE boot files
│   ├── bios/            # BIOS bootloaders
│   ├── efi64/           # UEFI bootloaders
│   ├── macrium/         # Macrium WinPE files
│   └── menus/           # iPXE menu scripts
├── config/               # Configuration files
│   └── nginx/           # Nginx reverse proxy config
├── docs/                 # Documentation
└── docker-compose.yml    # Main orchestration

Development Workflows

Backend Development

bash

cd coblyn/web/backend

# Install dependencies
pip install -r requirements.txt

# Run locally (outside Docker)
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Run tests
pytest

# Type checking
mypy src --ignore-missing-imports

# Linting
ruff check .
ruff format .

Frontend Development

bash

cd coblyn/web/frontend

# Install dependencies
npm install

# Run dev server
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Linting
npm run lint

Docker Development

bash

cd coblyn

# Rebuild specific service
docker compose build backend
docker compose up -d backend

# View logs
docker compose logs -f backend
docker compose logs -f kea

# Restart service
docker compose restart backend

# Full rebuild
docker compose down
docker compose build
docker compose up -d

Critical Development Patterns

1. DHCP Config Synchronization

Never edit Kea config files manually. Use the backend Kea client, which talks to the protected Unix socket shared with dhcp-kea:

python

# In backend code
from utils import kea_client

# After any device state change
kea_client.add_reservation(mac, ip)  # Sends a Kea command through /run/kea/kea-dhcp4-ctrl.sock

2. NFS Mount Operations

NFS mounts must use nsenter to mount on host filesystem:

python

import subprocess

subprocess.run([
    "nsenter", "--target", "1", "--mount", "--",
    "mount", "-t", "nfs", "-o", "nolock,vers=3",
    f"{server}:{path}", "/mnt/coblyn-images"
])

Menus are dynamically generated by the backend. Always use absolute HTTP URLs:

python

# Good
f"http://{server_ip}/tftpboot/macrium/boot.wim"

# Bad (relative paths don't work in iPXE)
"/tftpboot/macrium/boot.wim"

4. wimboot File Order

Critical: bootmgr must come before BCD:

ipxe

initrd --name bootmgr  ${http-root}/macrium/bootmgr  bootmgr
initrd --name BCD      ${http-root}/macrium/BCD      BCD
initrd --name boot.sdi ${http-root}/macrium/boot.sdi boot.sdi
initrd --name boot.wim ${http-root}/macrium/boot.wim boot.wim

Testing

Backend Tests (pytest)

The backend test suite lives in coblyn/web/backend/tests/ and uses in-memory SQLite for test isolation — no Docker required.

bash

cd coblyn/web/backend

# First time: create venv and install deps
python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows

pip install -r requirements.txt
pip install pytest pytest-asyncio pytest-cov httpx

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ -v --cov=. --cov-report=term-missing

# Run a specific test file
pytest tests/test_auth.py -v

Test files

File	Coverage	Tests
`tests/conftest.py`	Fixtures: in-memory DB, TestClient, JWT auth headers	—
`tests/test_auth.py`	Login, JWT validation, protected endpoints	11
`tests/test_inventory.py`	CRUD, MAC normalization, lifecycle (validate/reject/ban), bulk import	17
`tests/test_deployments.py`	Create, update, cancel, delete, stats, active	17
`tests/test_logs.py`	Level/source filtering, response structure	7

CI: The backend-test job in ci.yml runs pytest tests/ -v --cov=. --cov-report=xml automatically on every push to develop, testing and main.

Frontend Tests (vitest)

bash

cd coblyn/web/frontend

npm install

# Run all tests (vitest)
npm test

# Run with coverage
npm run test:coverage

# Watch mode during development
npm run test:watch

Manual Testing with VMs

For PXE boot testing, use Proxmox VMs with:

Disk: SATA (not VirtIO)
NIC: Intel E1000 (not VirtIO)
Boot Order: Network first

Debugging

Common Commands

bash

# Check container status
docker compose ps

# View backend logs
docker compose logs backend --tail 50 -f

# View DHCP logs
docker compose logs kea --tail 50 -f

# Kea is not exposed on HTTP. Inspect the backend-mediated DHCP endpoint instead.
curl -s http://localhost/api/dhcp/leases

# Check NFS mount
mount | grep coblyn
df -h /mnt/coblyn-images

# Backend health check
curl -s http://localhost/api/health | python3 -m json.tool

# Database inspection (PostgreSQL)
docker exec coblyn-db psql -U coblyn -c "SELECT mac_address, discovery_status, device_type FROM devices;"

Troubleshooting Guide

See the technical Knowledge Base for detailed troubleshooting procedures, including:

DHCP not working on Proxmox bridges
NFS mount issues
wimboot errors
WinPE disk/network problems
Docker DNS resolution

Code Conventions

Python (Backend)

Framework: FastAPI with async/await
ORM: SQLAlchemy 2.0 with mapped_column
Validation: Pydantic V2
Style: Follow PEP 8, use type hints
Comments: English
Linting: Ruff

JavaScript/React (Frontend)

Components: Functional components with hooks
Styling: Tailwind CSS with custom classes
i18n: Context-based with useT() hook
API: Centralized client in lib/api.js
Comments: English
Linting: ESLint

Commit Messages

Follow Conventional Commits:

bash

feat(dhcp): add quarantine range configuration
fix(backend): resolve NFS mount zombie state detection
docs(kb): update wimboot file order documentation
refactor(frontend): simplify device table component
test(backend): add DHCP sync integration tests

Deployment

Development

bash

docker compose up -d

Production

bash

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

Updating

bash

git pull origin main
docker compose build
docker compose up -d

Getting Help

Check the technical Knowledge Base.
Review the Skill: coblyn-pxe-system skill has all patterns
Check Issues: GitHub issues for known problems
Ask the AI: Use the coblyn-pxe-system skill for context-aware help

Last Updated: 2026-05-13 (Surgery — v1.16.0)

Coblyn Development Guide ​

Prerequisites ​

Development Environment Setup ​

1. Clone and Navigate ​

2. Configure Environment ​

3. Run Setup Script ​

4. Start Development Environment ​

Project Structure ​

Development Workflows ​

Backend Development ​

Frontend Development ​

Docker Development ​

Critical Development Patterns ​

1. DHCP Config Synchronization ​

2. NFS Mount Operations ​

3. iPXE Menu Generation ​

4. wimboot File Order ​

Testing ​

Backend Tests (pytest) ​

Test files ​

Frontend Tests (vitest) ​

Manual Testing with VMs ​

Debugging ​

Common Commands ​

Troubleshooting Guide ​

Code Conventions ​

Python (Backend) ​

JavaScript/React (Frontend) ​

Commit Messages ​

Deployment ​

Development ​

Production ​

Updating ​

Getting Help ​

Coblyn Development Guide

Prerequisites

Development Environment Setup

1. Clone and Navigate

2. Configure Environment

3. Run Setup Script

4. Start Development Environment

Project Structure

Development Workflows

Backend Development

Frontend Development

Docker Development

Critical Development Patterns

1. DHCP Config Synchronization

2. NFS Mount Operations

3. iPXE Menu Generation

4. wimboot File Order

Testing

Backend Tests (pytest)

Test files

Frontend Tests (vitest)

Manual Testing with VMs

Debugging

Common Commands

Troubleshooting Guide

Code Conventions

Python (Backend)

JavaScript/React (Frontend)

Commit Messages

Deployment

Development

Production

Updating

Getting Help