[![Documentation Status](https://readthedocs.org/projects/cnaas-nms/badge/?version=latest)](https://cnaas-nms.readthedocs.io/en/latest/?badge=latest) [![codecov](https://codecov.io/gh/SUNET/cnaas-nms/branch/master/graph/badge.svg)](https://codecov.io/gh/SUNET/cnaas-nms) [![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/downloads/release/python-3140/)

# 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](https://cnaas-nms.readthedocs.io/)

## Components

![CNaaS component architecture](cnaas-components-20190408.png?raw=true)

## Dependencies

Runtime dependencies are specified in `[project].dependencies` in _pyproject.toml_.
Development dependencies are in `[dependency-groups]` with two groups: `dev` and `docs`.

```sh
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:

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

#### Local Development

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

```sh
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:

```sh
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:

```sh
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:

```sh
./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:

```sh
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.