ndslive-setup 2026.2.0

Interactive setup wizard for NDS.Live development environment (Docker or Podman, Artifactory auth, pip config, tool installation)

ndslive-setup

Interactive setup wizard that configures your machine for working with NDS.Live. It handles Artifactory authentication, container registry access (Docker or Podman), Python package index configuration, and tool installation — so you can go from a fresh system to a working NDS.Live environment in minutes.

Installation

pip install ndslive-setup

Requires Python 3.10+.

If your system Python blocks pip install (common on Debian/Ubuntu and Homebrew), create a virtual environment first:

apt install python3-venv   # Debian/Ubuntu only
python3 -m venv ~/.nds/venv
source ~/.nds/venv/bin/activate
pip install ndslive-setup

Learn more about virtual environments: https://docs.python.org/3/library/venv.html

Quick Start

ndslive-setup

This launches a terminal-based wizard that walks you through every step.

Container Runtime Support

ndslive-setup works with Docker or Podman, in this resolution order:

1. The CONTAINER_RUNTIME=docker|podman environment variable (explicit override, wins over everything else).
2. The runtime saved to ~/.nds/setup.json from a previous run.
3. Auto-detection: Docker first (also covers Colima, Rancher Desktop, OrbStack — anything that exposes a docker CLI), then Podman.

Switching runtime after first run

If you later change your mind (e.g. got a Docker license after starting with Podman), you have three options:

• Re-run the wizard — when both Docker and Podman are installed, the Prerequisites step shows a picker; your choice is saved.
• ndslive-setup set-runtime docker|podman — scriptable, no TUI.
• CONTAINER_RUNTIME=docker … — per-invocation override that beats the saved value.

OS	Docker	Podman
Linux	✓	✓
macOS	✓	✓ — run podman machine start first
Windows	✓	✓ — Podman Desktop; auth.json under %APPDATA%

Container support is optional. If neither runtime is available the wizard skips registry-related steps and continues with Python package setup only.

Wizard Flow

The wizard guides you through six steps:

1. Welcome & Edition Selection

Choose your NDS.Live edition:

• Community — NDS.Live open tooling
• Member — NDS.Live + NDS.Classic tooling (requires NDS Association membership)

The edition determines which container registry and package catalog are available to you.

2. Prerequisites

Automated checks verify that your system is ready:

• Python >= 3.10 with pip
• venv module available
• Container runtime installed (Docker or Podman) with daemon running
• Network connectivity to Artifactory

A container runtime is optional — if none is available the wizard skips registry-related steps and continues with Python package setup only.

3. Artifactory Access

A single Artifactory identity token authenticates both container registry and Python package access. The wizard:

1. Verifies your credentials against the NDS Artifactory
2. Logs you into the container registry (docker login or podman login)
3. Writes an authenticated pip.conf with the NDS package index

If existing configuration is detected the wizard skips this step automatically. Use Back to revisit it if you want to reconfigure.

Note: The wizard requires an Artifactory identity token, not your SSO password. You can generate one under your Artifactory profile at artifactory.nds-association.org.

4. Python Environment

Optionally create a dedicated virtual environment for NDS tools. This keeps NDS packages isolated from your system Python. The default location is ~/.nds/venv but you can choose any path.

5. Install Tools

Select which NDS.Live tools to install:

• Python packages — installed via pip (into the venv if you created one)
• Container images — pulled from the Artifactory container registry

Already-cached container images are detected and shown so you can skip re-downloading them.

6. Summary

A recap of everything that was configured, plus next steps like activating your virtual environment and running your first tool.

CLI Commands

Beyond the wizard, ndslive-setup provides utility commands for day-to-day use:

ndslive-setup auth              # Headless authentication (no TUI) for scripted setup
ndslive-setup doctor            # Run diagnostics on your current setup
ndslive-setup status            # Show configuration at a glance
ndslive-setup set-runtime NAME  # Persist preferred runtime (docker or podman)
ndslive-setup reset             # Remove wizard state (keeps pip.conf and registry auth)
ndslive-setup reset --all       # Remove all NDS.Live configuration

Auth

ndslive-setup auth prompts for your Artifactory username + identity token and configures the container registry and pip index without launching the TUI. Useful for CI bootstraps, dotfile-driven onboarding, and any non-interactive context.

Doctor

Re-runs all prerequisite checks and inspects your container runtime and pip configuration. Useful after system changes or when something stops working.

Status

Quick table showing your current edition, container registry login state (Docker or Podman), and Python index configuration.

What Gets Configured

Component	Location	Purpose
Wizard state	~/.nds/setup.json	Remembers edition, username, and container runtime
pip config	~/.config/pip/pip.conf (Linux/macOS) / %USERPROFILE%\pip\pip.ini (Windows)	Authenticated NDS package index as primary, PyPI as fallback
Docker auth	~/.docker/config.json	Registry credentials (managed by Docker itself)
Podman auth	$XDG_RUNTIME_DIR/containers/auth.json (rootless), ~/.config/containers/auth.json, or %APPDATA%\containers\auth.json (Windows)	Registry credentials (managed by Podman itself)
Virtual env	~/.nds/venv (default)	Isolated Python environment for NDS tools

Requirements

• Python >= 3.10
• Docker or Podman (optional, for container-based tools)
• Network access to artifactory.nds-association.org

License

Apache-2.0