esa · axodentally · Jul 23, 2026 · Jul 23, 2026 · Jul 23, 2026 · Jul 23, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,9 @@
 .venv/
 tmp/
 __pycache__/
-*.pyc
+*.pyc
+
+# Build artifacts
+*.egg-info/
+build/
+dist/
diff --git a/README.md b/README.md
@@ -11,30 +11,23 @@
 
 ## Installation
 
-To install `NSE2`, you need to set up a Python virtual environment, install the required dependencies, and make the `nse2` tools accessible in your PATH.
+Create a virtual environment and install the project:
 
-First, create a clean virtual environment:
-```
-$ python3 -m venv .venv
+```sh
+python3 -m venv .venv
+source .venv/bin/activate
+pip install .
 ```
 
-The recommended approach to activate the environment and set up your PATH is to source `load_env.sh`. Do this before installing the dependencies:
-```
-$ source load_env.sh
-Activating virtual environment
-Adding tools/bin and tools/helpers to PATH
-$ pip3 install -r requirements.txt
-```
+When developing, use an editable install so changes take effect immediately:
 
-**Alternative approach using symlinks:**
-If you prefer not to source `load_env.sh` every time you start a new shell session, you can manually activate the environment, install the dependencies, and use the `install_symlinks.sh` script. This script installs all tools into your `.venv/bin` directory (or a user-supplied path), so they are automatically available whenever the virtual environment is active:
-```
-$ source .venv/bin/activate
-$ pip3 install -r requirements.txt
-$ ./install_symlinks.sh
+```sh
+pip install -e ".[dev]"
 ```
 
-Afterwards, all `nse2` tools are available to run network simulations.
+To pin dependencies to the exact versions tested in this repo (recommended), add `-c constraints.txt` to either command.
+
+Once installed, all `nse2_*` tools and helpers are available on PATH whenever the venv is active.
 
 ## Documentation
 

diff --git a/constraints.txt b/constraints.txt
@@ -0,0 +1,68 @@
+aiofiles==25.1.0
+aiohappyeyeballs==2.7.1
+aiohttp==3.14.3
+aiosignal==1.4.0
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.14.2
+attrs==26.1.0
+basedpyright==1.39.9
+bidict==0.23.1
+certifi==2026.7.22
+click==8.4.2
+contourpy==1.3.3
+cycler==0.12.1
+docutils==0.23
+fastapi==0.139.2
+fonttools==4.63.0
+frozenlist==1.8.0
+h11==0.16.0
+httpcore==1.0.9
+httptools==0.8.0
+httpx==0.28.1
+idna==3.18
+ifaddr==0.2.0
+iniconfig==2.3.0
+itsdangerous==2.2.0
+Jinja2==3.1.6
+kiwisolver==1.5.0
+lxml==6.1.1
+lxml_html_clean==0.4.5
+markdown2==2.5.5
+MarkupSafe==3.0.3
+matplotlib==3.11.1
+multidict==6.7.1
+networkx==3.6.1
+nicegui==3.15.0
+nodejs-wheel-binaries==24.16.0
+numpy==2.5.1
+orjson==3.11.9
+packaging==26.2
+pillow==12.3.0
+pluggy==1.6.0
+propcache==0.5.2
+pyaml==26.7.0
+pydantic==2.13.4
+pydantic_core==2.46.4
+Pygments==2.20.0
+pyparsing==3.3.2
+pytest==9.1.1
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.2
+python-engineio==4.13.3
+python-multipart==0.0.32
+python-socketio==5.16.3
+PyYAML==6.0.3
+simple-websocket==1.1.0
+six==1.17.0
+starlette==1.3.1
+tinycss2==1.5.1
+typing-inspection==0.4.2
+typing_extensions==4.16.0
+uvicorn==0.51.0
+uvloop==0.22.1
+watchfiles==1.2.0
+webencodings==0.5.1
+websockets==16.1.1
+wsproto==1.3.2
+yarl==1.24.5
diff --git a/doc/manual/chapters/installation.adoc b/doc/manual/chapters/installation.adoc
@@ -6,7 +6,7 @@ This section provides detailed instructions on how to install NSE2 on your syste
 Before installing NSE2, ensure that you have the following prerequisites:
 
 * A compatible operating system (Linux, macOS, or Windows)
-* Python 3.10 or higher
+* Python 3.11 or higher
 * pip (Python package installer)
 * Git (for cloning the repository)
 * Docker (for containerized environments)
@@ -19,21 +19,22 @@ NOTE: In theory, podman can be used instead of Docker, but it is not tested. Als
 
 . Clone the NSE2 repository from GitHub: `git clone https://github.com/esa/nse2.git`
 . Navigate to the NSE2 directory: `cd nse2`
-. Create a virtual environment: `python3 -m venv .venv`
-. Activate the virtual environment and set up tools in your PATH. We recommend using `load_env.sh` before installing the dependencies:
+. Create and activate a virtual environment, then install the project and its dependencies:
 +
 [source,bash]
 ----
-source load_env.sh
-pip install -r requirements.txt
+python3 -m venv .venv
+source .venv/bin/activate
+pip install ".[dev]"
 ----
 +
-**Alternative approach using symlinks:**
-If you prefer not to source `load_env.sh` in every new shell session, you can manually activate the environment, install the dependencies, and use the `install_symlinks.sh` script to install all tools into your `.venv/bin` directory:
+All `nse2_*` tools and helpers are installed into the virtual environment and available on PATH whenever the venv is active. `PYTHONPATH` is handled automatically.
++
+TIP: For pinning dependencies to the exact versions tested in this repository, add `-c constraints.txt` to the `pip install` command.
+
+. **For development:** use an editable install so that changes to the source code take effect immediately without reinstalling:
 +
 [source,bash]
 ----
-source .venv/bin/activate
-pip install -r requirements.txt
-./install_symlinks.sh
+pip install -e ".[dev]"
 ----
diff --git a/install_symlinks.sh b/install_symlinks.sh
diff --git a/load_env.sh b/load_env.sh
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nse2"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "matplotlib",
+    "networkx",
+    "nicegui>=3.3.0",
+    "pyaml",
+    "python-dateutil",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "basedpyright>=1.39",
+]
+
+[project.scripts]
+nse2_contacts   = "tools.contact_player.contact_player:main"
+nse2_cmd        = "tools.bin.nse2_cmd:main"
+nse2_mgr        = "tools.mgr.mgr:main"
+nse2_netviz     = "tools.netviz.netviz:main"
+csv_to_ccp      = "tools.helpers.csv_to_ccp:main"
+csv_to_compose  = "tools.helpers.csv_to_compose:main"
+random_contacts = "tools.helpers.random_contacts:main"
+
+[tool.setuptools]
+script-files = [
+    "tools/bin/nse2_actions",
+    "tools/bin/nse2_sh",
+    "tools/bin/nse2_topo",
+]
+
+[tool.setuptools.packages.find]
+include = ["tools", "tools.*"]
+
+[tool.basedpyright]
+reportUnusedCallResult = false
+reportImplicitStringConcatenation = false
diff --git a/requirements.txt b/requirements.txt
diff --git a/tools/__init__.py b/tools/__init__.py
diff --git a/tools/bin/__init__.py b/tools/bin/__init__.py
diff --git a/tools/bin/nse2_cmd → tools/bin/nse2_cmd.py b/tools/bin/nse2_cmd → tools/bin/nse2_cmd.py
diff --git a/tools/bin/nse2_topo b/tools/bin/nse2_topo
@@ -32,7 +32,7 @@ COMPOSE_FILE=$1
 echo "Starting containers and network topology for scenario $COMPOSE_FILE"
 
 # Ensure proper cleanup on exit or abort
-trap cleanup EXIT
+trap cleanup EXIT INT TERM
 
 $DOCKERCMD compose -f $COMPOSE_FILE up --force-recreate --build --remove-orphans -d
 

diff --git a/tools/contact_player/__init__.py b/tools/contact_player/__init__.py
diff --git a/tools/dslproxy/__init__.py b/tools/dslproxy/__init__.py
diff --git a/tools/helpers/__init__.py b/tools/helpers/__init__.py
diff --git a/tools/helpers/get-fixed-links.py → tools/helpers/get_fixed_links.py b/tools/helpers/get-fixed-links.py → tools/helpers/get_fixed_links.py
diff --git a/tools/helpers/random-contacts.py → tools/helpers/random_contacts.py b/tools/helpers/random-contacts.py → tools/helpers/random_contacts.py
diff --git a/tools/mgr/__init__.py b/tools/mgr/__init__.py
diff --git a/tools/mgr/mgr.py b/tools/mgr/mgr.py
@@ -9,7 +9,7 @@
 import networkx as nx
 import asyncio
 
-from helpers import *
+from tools.mgr.helpers import *
 
 # regex to extract rate, delay, loss, jitter from tc output
 tc_rate = re.compile(r"rate ([0-9]+[KMG]bit)")
@@ -301,8 +301,10 @@ async def draw_links(links_area: ui.scroll_area, compose_file: str):
                                     print(e)
 
                 bg = "#f3f4f6" if is_active else "#fde8e8"
-                with ui.row().classes("place-items-center w-full").style(
-                    f"background-color: {bg}"
+                with (
+                    ui.row()
+                    .classes("place-items-center w-full")
+                    .style(f"background-color: {bg}")
                 ):
                     if is_active:
                         ui.icon("cloud_done").classes("text-green-500").style(
@@ -347,7 +349,6 @@ def draw_map(map_area: ui.scroll_area):
         map_area.clear()
 
         with ui.matplotlib(figsize=(8, 5)).figure as fig:
-
             # x = np.linspace(0.0, 5.0)
             # y = np.cos(2 * np.pi * x) * np.exp(-x)
             ax = fig.gca()
@@ -437,13 +438,6 @@ def ui_main(compose_file: str, contact_plan: str):
         5.0,
         lambda: linkstate_timer(compose_file, links_area, map_area),
     )
-    ui.run(
-        reload=True,
-        title="Docker TestBed Manager",
-        show=False,
-        port=8800,
-        host="127.0.0.1",
-    )
 
 
 def main():
@@ -469,7 +463,18 @@ def main():
     # s = time.time()
     # print(get_container_interfaces_parallel(compose_file))
     # print(f"Elapsed time: {time.time() - s}")
-    ui_main(compose_file, contact_plan)
+
+    def build_page():
+        ui_main(compose_file, contact_plan)
+
+    ui.run(
+        root=build_page,
+        reload=False,
+        title="Docker TestBed Manager",
+        show=False,
+        port=8800,
+        host="127.0.0.1",
+    )
 
 
 if __name__ in {"__main__", "__mp_main__"}:

diff --git a/tools/netviz/__init__.py b/tools/netviz/__init__.py