Backend¶
Async FastAPI app under backend/app/. Driven by Pydantic schemas, talks to Postgres via SQLAlchemy async, and persists lab topology to JSON files on disk.
Module layout¶
backend/app/
├── main.py # FastAPI application + router wiring
├── config.py # Settings (Pydantic BaseSettings)
├── database.py # Async engine + session factory
├── dependencies.py # FastAPI dependency injectors (auth, lab lookup, etc.)
├── core/ # Cross-cutting concerns (logging, error handlers)
├── models/ # SQLAlchemy models — users, sessions, audit
├── schemas/ # Pydantic request/response models
├── routers/ # HTTP + WebSocket route handlers
└── services/ # Business logic — pure Python, no FastAPI coupling
Routers¶
Each module under routers/ mounts an APIRouter at a path prefix:
| Router | Prefix | Surface |
|---|---|---|
auth.py |
/api/auth |
Session login / logout / current-user. |
users.py |
/api/users |
User CRUD (admin-only). |
folders.py |
/api/folders |
Lab folder hierarchy. |
labs.py |
/api/labs |
Lab CRUD, node start/stop, runtime control, external-console endpoints. |
links.py |
/api/labs/{lab}/links |
Link create / delete / list. |
networks.py |
/api/labs/{lab}/networks |
Network create / patch / delete + runtime bridge reconciliation. |
listing.py |
/api/list |
Vendor template + image listings. |
system.py |
/api/system |
Health, status, editable settings, environment info. |
dynamips.py |
/api/dynamips |
Idle-PC calibration API. |
docker_images.py |
/api/docker/images |
Local Docker image inspection for node templates. |
library.py |
/api/library |
User image library management. |
manage.py |
/api/manage |
Lab + node management views. |
ws.py |
/ws |
WebSocket fan-out for runtime state. |
Services¶
Each service owns one concern. Routers stay thin and delegate everywhere:
| Service | What it owns |
|---|---|
auth_service |
Password hashing, session token issuance, role checks. |
lab_service |
Lab JSON read/write, validation, schema upgrades. |
lab_lock |
Cooperative file lock for lab JSON writes. |
link_service |
Link create / delete with cascading runtime detach. |
link_utils |
Pure helpers for link endpoint shape. |
network_service |
Bridge create / delete / rename, display-name uniqueness, NAT-Cloud + Bridge-Cloud runtime state. |
node_runtime_service |
Start / stop nodes, attach / detach interfaces at runtime, console ports and proxies. |
runtime/ |
Per-kind launchers (iol, dynamips) used by the runtime service. |
runtime_mutex |
Per-(lab, node, iface) async locks gating runtime mutations. |
runtime_pids |
PID tracking and exit-watcher per running node. |
host_net |
Shell-out to the privileged helper for bridge / veth / TAP ops. |
mac_registry |
Live-MAC reader + planned-MAC comparator. |
template_service |
Template discovery and instantiation. |
qemu_versions |
Side-by-side QEMU version resolution (#278). |
docker_image_service |
Local Docker image listing/inspection. |
image_library_service |
User image library. |
bridge_cloud_service |
Host Bridge-Cloud (br-eth*) listing. |
cloud_inventory_service |
NAT-Cloud egress inventory. |
iourc_service |
IOURC license storage/status for IOL nodes. |
folder_service |
Lab folder hierarchy. |
guacamole_db_service |
Wire console connections into the Guacamole DB. |
html5_service |
HTML5 console URL builder. |
ws_hub |
WebSocket fan-out — subscribe-by-lab, broadcast runtime events. |
EVE-NG importer¶
The EVE-NG importer is not part of the running backend. It lives at backend/scripts/import_eveng/ and runs as an offline CLI:
backend/scripts/import_eveng/
├── cli.py # argparse entry; resolves modes, walks, plans, migrates
├── walker.py # KIND_QEMU / KIND_DYNAMIPS / KIND_IOL / KIND_DOCKER discovery
├── copy_engine.py # Idempotent move+symlink / copy + sha256 verify (#271)
├── idempotency.py # Per-file skip decisions
├── migrate.py # Top-level run orchestrator (step reporter wiring)
├── manifest.py # Manifest schema + writer
├── permissions.py # chown / chmod after migration
├── _app_owner.py # Service-user resolution (NOVA_VE_SERVICE_USER → NOVA_VE_OWNER → nova-ve)
├── _hash.py # sha256 helper
├── logging_setup.py # Step reporter + rotating run-log config (#271)
├── template_schema.py # Result schema for adapter convert()
├── parsers/ # PHP / YAML parsers for EVE-NG source templates
└── adapters/ # One module per vendor (arista_veos, cisco_iol, …)
See CLI — import-eveng-templates for the user-facing flags and Vendor coverage for the adapter list.
Testing¶
# Full suite
cd backend && .venv/bin/python -m pytest tests/
# A subset
.venv/bin/python -m pytest tests/test_networks_api.py -k "test_create_network_duplicate"
# Importer-only
.venv/bin/python -m pytest tests/scripts/test_import_eveng/
Integration tests use a real Postgres via the host package; unit tests for services run without it.