From d09bdcd6b9fd6d815d6272a7bc337b410b19b665 Mon Sep 17 00:00:00 2001 From: Tom van der Lee Date: Thu, 24 Sep 2026 10:25:38 +0000 Subject: Add uv and a rootless Docker runtime on NixOS hosts uv joins the CLI package list. Docker's daemon is now actually managed on NixOS hosts too, in rootless mode (per-user systemd service, no docker-group root-equivalent access), rather than leaving the runtime entirely externally-managed as before -- the already-installed docker CLI picks it up automatically via DOCKER_HOST. This is a documented, narrow exception to developer-environment's client-only tools policy; kubectl and awscli2 remain unaffected. Archives add-uv-and-docker-runtime and syncs the new container-runtime capability plus the narrowed developer-environment requirement into the main specs. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01HngxrvqEzq8oBEBDtrYJyB --- .../.openspec.yaml | 2 ++ .../2026-09-24-add-uv-and-docker-runtime/design.md | 40 ++++++++++++++++++++++ .../proposal.md | 26 ++++++++++++++ .../specs/container-runtime/spec.md | 19 ++++++++++ .../specs/developer-environment/spec.md | 12 +++++++ .../2026-09-24-add-uv-and-docker-runtime/tasks.md | 14 ++++++++ 6 files changed, 113 insertions(+) create mode 100644 openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml create mode 100644 openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md create mode 100644 openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md create mode 100644 openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md create mode 100644 openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md create mode 100644 openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md (limited to 'openspec/changes/archive') diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml new file mode 100644 index 0000000..75289e4 --- /dev/null +++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-24 diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md new file mode 100644 index 0000000..6d25717 --- /dev/null +++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/design.md @@ -0,0 +1,40 @@ +## Context + +See proposal.md - Why. This covers the Docker daemon decisions; `uv` is a plain CLI-package addition with nothing else to decide. + +Confirmed by reading the pinned `nixos-unstable` nixpkgs' `nixos/modules/virtualisation/docker-rootless.nix`: +- `virtualisation.docker.rootless.enable = true;` runs `dockerd-rootless` as a **user** systemd service (`systemd.user.services.docker`, `wantedBy = [ "default.target" ]`), gated by `ConditionUser = "!root"` — it does not run as a system-level root daemon and does not use the `docker` group at all (that's a rootful-mode concept only). +- `virtualisation.docker.rootless.setSocketVariable = true;` exports `DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock` for the user automatically, so the already-installed `docker` CLI (from `modules/home/dev-tools.nix`) finds the daemon with no per-user shell config. +- Rootless mode needs `newuidmap`/`newgidmap` (from `pkgs.shadow`, via `/run/wrappers`) and subuid/subgid ranges for the user; confirmed in `nixos/modules/config/users-groups.nix` that any `isNormalUser` account (which `tom` already is, in `modules/nixos/common.nix`) gets `autoSubUidGidRange = mkDefault true` for free — no extra config needed for `tom` specifically. + +## Goals / Non-Goals + +**Goals:** +- `docker`/`docker-compose` (already provisioned via `modules/home/dev-tools.nix`) work out of the box on any NixOS host from this flake, with no manual daemon setup or `DOCKER_HOST` export. +- No root-owned daemon process, and no `docker`-group privilege-escalation path (the well-known rootful-Docker security concern, since group membership in `docker` is root-equivalent). + +**Non-Goals:** +- Rootful Docker, or a `docker` group — explicitly not used, per rootless choice. +- Managing Docker on the standalone (non-NixOS) `tom@linux`/`tom@darwin` home-manager profiles — those keep relying on an externally-managed runtime (Docker Desktop/OrbStack), unchanged from today. +- Any Kubernetes/cloud runtime — `kubectl`/`awscli2` remain explicitly client-only, per the narrowed `developer-environment` requirement. +- TLS/remote Docker API exposure, custom daemon settings (registries, storage drivers, etc.) — only the daemon itself is turned on, with defaults. + +## Decisions + +**Decision: rootless over rootful Docker.** +- User's explicit choice. Alternatives considered: rootful (`virtualisation.docker.enable = true;` + `users.users.tom.extraGroups = [ "docker" ]`) is the more common/simpler setup and has slightly broader compatibility (e.g. binding privileged ports below 1024, some volume-permission edge cases behave more predictably), but membership in the `docker` group is a well-documented root-equivalent privilege escalation (a container can bind-mount `/` and modify the host as root). Rootless avoids that entirely at the cost of those edge-case compatibility gaps. + +**Decision: unconditional on every NixOS host, added inline to `modules/nixos/common.nix`.** +- User's explicit choice, matching the existing pattern for GNOME/SSH/printing/avahi in that same file — no per-host opt-in mechanism exists elsewhere in this repo for system services, so introducing one just for Docker would be an inconsistent one-off. Added inline rather than as a new `modules/nixos/docker.nix` file, consistent with how every other unconditional system-level concern in this repo (GNOME, SSH, dconf, pipewire, printing) already lives directly in `common.nix` rather than being split out. + +**Decision: rely on nixpkgs' default `autoSubUidGidRange` rather than setting explicit `subUidRanges`/`subGidRanges` on `tom`.** +- Simpler, and confirmed correct by reading the actual default-assignment logic in `users-groups.nix` (`isNormalUser` + no explicit ranges set → `autoSubUidGidRange` defaults to `true`). Setting an explicit range would only add a pin to maintain for no behavioral benefit. + +**Decision: narrow the existing `developer-environment` "client-only" requirement rather than leaving it as-is and letting the new `container-runtime` capability silently contradict it.** +- Alternatives considered: leaving the old requirement's blanket wording untouched and only adding `container-runtime` was rejected — a future reader of "Container and cloud tools are client-only" would have no indication Docker is now an exception, and `openspec validate`'s spec/behavior contract would be misleading. Explicitly naming Docker as the carved-out exception keeps the two capabilities' specs mutually consistent. + +## Risks / Trade-offs + +- [Rootless Docker has real compatibility gaps vs. rootful: binding ports <1024 needs extra config, some third-party images assume a rootful daemon, performance can be slightly lower due to the userspace network stack (slirp4netns/VPNKit-style)] → Accepted trade-off per the user's explicit security-over-compatibility choice; not mitigated further in this change. +- [The user systemd service only starts on user login (`wantedBy = [ "default.target" ]` at the *user* manager level), not at boot before any login] → Expected and consistent with rootless Docker's design (it's inherently tied to a logged-in user's session); not a regression from "no daemon at all" today. +- [`docker` package is already installed twice in concept — once via `modules/home/dev-tools.nix`'s `pkgs.docker` and again via `virtualisation.docker.rootless.package` which nixpkgs adds to `environment.systemPackages`] → Harmless: both resolve to the same nixpkgs `docker` derivation and Nix store paths dedupe; no functional conflict, just two provisioning paths converging on the same package (home-manager for cross-platform coverage, NixOS module as an inherent side effect of enabling the service). diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md new file mode 100644 index 0000000..74391f1 --- /dev/null +++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/proposal.md @@ -0,0 +1,26 @@ +## Why + +Tom wants `uv` (the Python package/project manager) available as a CLI tool, and — after clarifying the request — wants NixOS hosts to actually run a Docker daemon rather than just the client CLI that's already provisioned, so `docker run`/`docker build` work without a separately-managed runtime. + +## What Changes + +- Add `pkgs.uv` to `modules/home/dev-tools.nix`'s CLI package list. Verified against the flake's pinned `nixos-unstable` nixpkgs: dual Apache-2.0/MIT licensed (free), broad platform support including `aarch64-darwin`/`x86_64-linux`/`aarch64-linux`. No spec change needed — `developer-environment`'s existing "Developer CLI tools are provisioned via the shared home profile" requirement already covers adding another evidenced CLI tool to the list, the same reasoning previously used for `bitwarden-cli` and `claude-code`. +- Enable a **rootless** Docker daemon (`virtualisation.docker.rootless.enable = true;` plus `virtualisation.docker.rootless.setSocketVariable = true;`) unconditionally on every NixOS host, in `modules/nixos/common.nix`, alongside the other unconditional host-level services (GNOME, SSH, printing). Rootless runs the daemon as a per-user systemd user service under `tom`'s own UID rather than as root — no `docker`-group privilege-escalation path, unlike the standard rootful setup. `setSocketVariable` makes the already-installed `docker` CLI (from `dev-tools.nix`) find the rootless socket automatically via `$DOCKER_HOST`, with no extra per-user config. +- **This reverses part of the existing "Container and cloud tools are client-only" policy** for Docker specifically: `developer-environment`'s spec currently states container/cloud tools SHALL NOT manage the underlying runtime. Docker becomes an explicit, called-out exception; `kubectl` and `awscli2` remain client-only as before (no Kubernetes cluster or cloud account is being provisioned). +- **BREAKING**: none — additive only. Existing `docker`/`docker-compose` CLI usage against an externally-managed runtime (e.g. Docker Desktop/OrbStack on macOS) is unaffected; this only changes NixOS hosts, where no runtime was being managed before. + +## Capabilities + +### New Capabilities +- `container-runtime`: provides a working, unprivileged (rootless) Docker container runtime on every NixOS host built from this flake, so the already-provisioned `docker`/`docker-compose` CLI tools have something to talk to without a separately-managed daemon. + +### Modified Capabilities +- `developer-environment`: narrow the "Container and cloud tools are client-only" requirement to explicitly exclude Docker, which is now backed by the `container-runtime` capability on NixOS hosts; `kubectl` and `awscli2` remain covered by the original client-only rule. + +## Impact + +- **Affected code**: `modules/home/dev-tools.nix` (add `pkgs.uv`), `modules/nixos/common.nix` (add `virtualisation.docker.rootless.enable`/`setSocketVariable`). +- **Not affected**: `lib/unfree-allowlist.nix` (uv is free-licensed; Docker's daemon package in nixpkgs is Apache-2.0), `modules/home/desktop-apps.nix`. +- **Dependencies**: nixpkgs' `uv` and `docker` (already used) packages, both already present in the pinned `nixos-unstable` input; no new flake inputs. +- **Platforms**: `uv` is provisioned cross-platform like the rest of `dev-tools.nix`. The Docker daemon change only applies to NixOS hosts (`modules/nixos/common.nix`); it has no effect on the standalone `tom@linux`/`tom@darwin` home-manager profiles, which continue to rely on whatever runtime is already present on that machine (e.g. Docker Desktop/OrbStack on macOS), exactly as documented today. +- **Known limitation, out of scope**: no Docker daemon TLS/remote-access configuration, no Docker Compose v1-vs-v2 plugin wiring changes, and no `nix-ld`/extra container-toolchain packages beyond what's already provisioned — this only turns on the daemon itself. diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md new file mode 100644 index 0000000..e0565c6 --- /dev/null +++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/container-runtime/spec.md @@ -0,0 +1,19 @@ +## Purpose + +Provides a working, unprivileged Docker container runtime on every NixOS host built from this flake, so the already-provisioned Docker CLI tooling has a daemon to talk to without a separately-managed installation step. + +## ADDED Requirements + +### Requirement: A rootless Docker daemon runs on every NixOS host +Every NixOS host built from this flake's shared system module SHALL run a Docker daemon in rootless mode (as the user's own account, not as root), without requiring per-host opt-in. + +#### Scenario: Daemon available after boot +- **WHEN** a NixOS host built from this flake's shared system module finishes booting and the user logs in +- **THEN** a Docker daemon is running under that user's own account, not as root + +### Requirement: The Docker CLI connects to the rootless daemon without manual configuration +A user on a NixOS host built from this flake's shared system module SHALL be able to run Docker CLI commands (e.g. `docker run`, `docker build`) against the rootless daemon without manually setting `DOCKER_HOST` or other connection configuration. + +#### Scenario: Docker command works out of the box +- **WHEN** a user runs a `docker` CLI command on a NixOS host built from this flake's shared system module +- **THEN** the command reaches the rootless daemon and executes, without the user having exported `DOCKER_HOST` or written any Docker connection config themselves diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md new file mode 100644 index 0000000..8a76849 --- /dev/null +++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/specs/developer-environment/spec.md @@ -0,0 +1,12 @@ +## MODIFIED Requirements + +### Requirement: Container and cloud tools are client-only +Container and cloud-related packages provisioned by this capability SHALL provide client/CLI functionality only; they SHALL NOT attempt to provide or manage the underlying runtime or service (e.g. a Kubernetes cluster or cloud account), with one exception: Docker's runtime is managed on NixOS hosts by the separate `container-runtime` capability. Outside of NixOS hosts, and for every other tool (`kubectl`, `awscli2`), no corresponding runtime or account is installed or managed. + +#### Scenario: No runtime is installed or managed +- **WHEN** a container or cloud CLI tool other than Docker is provisioned by the shared home profile +- **THEN** no corresponding daemon, virtual machine, or account configuration is installed or managed by this capability — the tool simply connects to whatever runtime or account is already configured on the system + +#### Scenario: Docker's runtime is the documented exception on NixOS +- **WHEN** the Docker CLI is provisioned by the shared home profile on a NixOS host built from this flake's shared system module +- **THEN** a Docker runtime is available via the separate `container-runtime` capability, rather than being left entirely unmanaged diff --git a/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md new file mode 100644 index 0000000..14b6dfc --- /dev/null +++ b/openspec/changes/archive/2026-09-24-add-uv-and-docker-runtime/tasks.md @@ -0,0 +1,14 @@ +## 1. uv CLI tool + +- [x] 1.1 Add `pkgs.uv` to the package list in `modules/home/dev-tools.nix` and verify `nix eval '.#homeConfigurations."tom@linux".config.home.packages'` and `..."tom@darwin"...` both include it. + +## 2. Rootless Docker daemon + +- [x] 2.1 Add `virtualisation.docker.rootless.enable = true;` and `virtualisation.docker.rootless.setSocketVariable = true;` to `modules/nixos/common.nix`, alongside the other unconditional host-level services. +- [x] 2.2 Build a NixOS host's system closure with `hosts/test-vm` visible via the `path:` flake-ref scheme (it's git-untracked): `nix build 'path:/home/tom/desktop-flake#nixosConfigurations.test-vm.config.system.build.toplevel'`, and verify it succeeds. +- [x] 2.3 Inspect the built closure's `systemd.user.services.docker` unit (e.g. via the closure's `etc/systemd/user/docker.service` or an equivalent generated unit file) and verify it runs `dockerd-rootless` with `ConditionUser=!root`, confirming the daemon is wired as a rootless per-user service rather than a root daemon. +- [x] 2.4 On a booted host, after logging in as `tom`, verify `docker run --rm hello-world` succeeds with no manual `DOCKER_HOST` export or other setup — this needs an interactive login session and can't be exercised from this sandbox. + +## 3. Spec sync + +- [x] 3.1 Verify `openspec validate --change add-uv-and-docker-runtime --strict` passes once the above are implemented, confirming both delta specs match the shipped behavior. -- cgit v1.3