Metadata-Version: 2.4
Name: ndslive-setup
Version: 2026.1.0.post16
Summary: Interactive setup wizard for NDS.Live development environment (Docker or Podman, Artifactory auth, pip config, tool installation)
Author-email: NDS Association <support@nds-association.org>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/ndsev/ndslive-setup
Project-URL: Repository, https://github.com/ndsev/ndslive-setup
Project-URL: Issues, https://github.com/ndsev/ndslive-setup/issues
Keywords: nds,ndslive,setup,artifactory,development-tools,docker,podman,container-runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.50.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Dynamic: license-file

# ndslive-setup

Interactive setup wizard that configures your machine for working with
[NDS.Live](https://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

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

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

```bash
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
