CNaaS-NMS

Campus Network-as-a-Service - Network Management System. Software to automate management of a campus network (LAN). This is an open source software developed as part of SUNETs managed service.

Planned features:

1. Zero-touch provisioning of switches
2. Automation of common changes for campus LAN
3. Automated procedure for firmware upgrades
4. Multi-vendor support

Documentation

Components

Dependencies

Runtime dependencies are specified in [project].dependencies in pyproject.toml. Development dependencies are in [dependency-groups] with two groups: dev and docs.

uv sync                   # runtime dependencies
uv sync --group dev       # test/lint tools (pytest, mypy, ruff, etc.)
uv sync --group docs      # documentation tools (sphinx)

Requirements

Docker and docker compose or:

1. Python 3.14
2. uv sync (and uv sync --group dev for development)
3. SQL database, Redis

Installation

Docker

Build and run the production image:

docker compose -f docker/docker-compose.yaml build

Local Development

Local development builds on the test compose (with test data) and adds source mounting:

docker compose -f docker/docker-compose_test.yaml -f docker/docker-compose.dev.yaml build
docker compose -f docker/docker-compose_test.yaml -f docker/docker-compose.dev.yaml up -d

The dev overlay automatically:

• Mounts your local src/ directory with hot reloading (uwsgi auto-reloads on Python file changes)
• Generates JWT keypair and CA certificates
• Clones integrationtest templates and settings repositories

Access points:

• API: https://localhost/api/v1.0/
• Swagger UI: https://localhost/api/doc/

Get a dev token for API access:

docker compose -f docker/docker-compose_test.yaml -f docker/docker-compose.dev.yaml exec cnaas_api cat /opt/cnaas/jwtcert/dev-token

Use the token:

• Swagger UI: Click "Authorize", enter Bearer <token>, then click "Authorize"
• curl: curl -ks -H "Authorization: Bearer <token>" https://localhost/api/v1.0/devices

Tear down containers when done:

docker compose -f docker/docker-compose_test.yaml -f docker/docker-compose.dev.yaml down

Venv

Install locally with uv, which creates and manages a virtualenv automatically:

uv sync
cp etc/db_config.yml.sample /etc/cnaas-nms/db_config.yml

Edit db_config.yml to point to your SQL and Redis database.

Test

Local with Docker

Run tests locally with pre-provisioned test data:

./docker/run-tests-local.sh

This script:

• Starts PostgreSQL and Redis containers if not running
• Clones test templates/settings to .test-data/ (once, reused on subsequent runs)
• Runs unit tests first, then integration tests

Integration tests

Integration tests need Containerlab running, and the integration-tools dependency group (coverage/pytest), which is not installed by default. Build the api image with the build arg to include it:

cd docker
INCLUDE_INTEGRATION_TOOLS=1 docker compose build cnaas_api
cd ../test && AUTOTEST=1 ./integrationtests.sh

Authorization

Currently we can use two styles for the authorization. We can use the original style or use OIDC style. For OIDC we need to define some env variables or add a auth_config.yaml in the config. The needed variables are: OIDC_CONF_WELL_KNOWN_URL, OIDC_CLIENT_SECRET, OIDC_CLIENT_ID, FRONTEND_CALLBACK_URL and OIDC_ENABLED. To use the OIDC style the last variable needs to be set to true.

License

Copyright (c) 2019 - 2020, SUNET (BSD 2-clause license)

See LICENSE.txt for more info.