confctl 2.2.3 → 3.0.0

data/README.md

@@ -21,76 +21,160 @@ machines.
 * [Nix](https://nixos.org)
 
 ## Quick start
-1. Either install confctl as a gem:
+### Flake-based configuration (recommended)
+
+confctl works best with a flake-based configuration repository. The repository
+defines flake inputs (nixpkgs/vpsadminos/etc.), maps them into **channels**, and
+machines select channels via `cluster.<name>.inputs.channels`.
+
+Create a new configuration directory and initialize it:
+
+```bash
+mkdir cluster-configuration
+cd cluster-configuration
+confctl init
+```
+
+`confctl init` generates a `flake.nix` like this:
+
+```nix
+{
+  description = "confctl configuration (flake)";
+
+  inputs = {
+    confctl.url = "github:vpsfreecz/confctl";
+
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+    # vpsadminos.url = "github:vpsfreecz/vpsadminos/staging";
+    # vpsadminos.inputs.nixpkgs.follows = "nixpkgs";
+  };
+
+  outputs = inputs@{ self, confctl, ... }:
+    let
+      channels = {
+        nixos-unstable = { nixpkgs = "nixpkgs"; };
+
+        # vpsadminos = {
+        #   nixpkgs = "nixpkgs";
+        #   vpsadminos = "vpsadminos";
+        # };
+      };
+
+      confctlOutputs = confctl.lib.mkConfctlOutputs {
+        confDir = ./.;
+        inherit inputs channels;
+      };
+    in
+    {
+      confctl = confctlOutputs;
+
+      # Shell modes:
+      # - minimal: no Gemfile, best default
+      # - tools: Gemfile for repo tools such as overcommit or rubocop
+      # - bundled-confctl: Gemfile includes confctl and scripts/ can use bundle gems
+      devShells.x86_64-linux.default = confctl.lib.mkConfigDevShell {
+        system = "x86_64-linux";
+        mode = "minimal";
+      };
+    };
+}
 ```
-gem install confctl
+
+The optional `vpsadminos` input is commented out by default because most new
+configurations deploy NixOS only.
+
+Then enter the dev shell:
+
+```bash
+nix develop
 ```
 
-Or clone this repository:
+This makes `confctl` available from the pinned flake input package and exposes
+its man pages on `MANPATH`.
+
+For the Bundler modes, commit `Gemfile.lock` whenever possible. `confctl` can
+bootstrap those shells without it, but the lockfile makes CI and local shells
+reproducible.
+
+Before the first build or deploy, make sure the per-user gcroot directory
+exists:
 
+```bash
+sudo mkdir -p /nix/var/nix/gcroots/per-user/$USER
+sudo chown $USER /nix/var/nix/gcroots/per-user/$USER
 ```
-git clone https://github.com/vpsfreecz/confctl
+
+Add a new machine to be deployed:
+
+```bash
+confctl add my-machine
 ```
 
-This guide assumes you have cloned the repository, because otherwise man will
-not find confctl's manual pages. If you install confctl using gem, you can
-ignore steps with `shell.nix`.
+You can now edit the machine's configuration in directory `cluster/my-machine`.
 
-2. Create a new directory, where your confctl-managed configuration will be
-stored:
+Build the machine:
 
+```bash
+confctl build my-machine
 ```
-mkdir cluster-configuration
+
+Deploy the machine:
+
+```bash
+confctl deploy my-machine
 ```
-3. Create `shell.nix` and import the same file from confctl:
+
+To update flake inputs, use the `confctl inputs ...` commands:
+
+```bash
+confctl inputs ls
+confctl inputs update --commit nixpkgs
+confctl inputs channel update --commit nixos-unstable nixpkgs
 ```
-cd cluster-configuration
+
+If you are migrating an existing configuration repository that uses `configs/swpins.nix`
+and the `swpins/` directory, confctl includes an interactive helper: `confctl migrate swpins-to-flakes`
+(use `--dry-run` to preview). See [docs/swpins-to-flakes.md](docs/swpins-to-flakes.md).
+
+### Legacy configuration (non-flake)
+
+The original non-flake workflow is still supported. Use `confctl init --swpins`
+instead of `confctl init`; the `confctl add`, `confctl build`, and `confctl deploy`
+workflow is otherwise the same as above.
+
+Legacy non-flake configuration repositories can continue importing
+[`shell.nix`](shell.nix). If you use this workflow, create `shell.nix` in the
+configuration directory and adjust the import path as needed:
+
+```bash
 cat > shell.nix <<EOF
 import ../confctl/shell.nix
 EOF
 ```
 
-4. Enter the `nix-shell`. This will make confctl available and install its
-dependencies into `.gems/`:
-```
+Enter the `nix-shell`. This uses the legacy bundled-confctl shell and installs
+confctl's dependencies into `.gems/`:
+
+```bash
 nix-shell
 ```
 
 From within the shell, you can access the [manual](./man/man8/confctl.8.md)
 and a list of [configuration options](./man/man8/confctl-options.nix.8.md):
 
-```
+```bash
 man confctl
 man confctl-options.nix
 ```
 
-5. Initialize the configuration directory with confctl:
-```
-confctl init
-```
-
-6. Add a new machine to be deployed:
-```
-confctl add my-machine
-```
-
-You can now edit the machine's configuration in directory `cluster/my-machine`.
+Update pre-configured software pins to fetch current nixpkgs. In flake-based
+configurations, use `confctl inputs ...` instead:
 
-7. Update pre-configured software pins to fetch current nixpkgs:
-```
+```bash
 confctl swpins update
 ```
 
-8. Build the machine
-```
-confctl build my-machine
-```
-
-9. Deploy the machine
-```
-confctl deploy my-machine
-```
-
 ## Example configuration
 Example configuration, which can be used as a starting point, can be found in
 directory [example/](example/).
@@ -115,11 +199,14 @@ See also existing configurations:
     │   └── swpins.nix          # User-defined software pin channels
     ├── data/                   # User-defined datasets available in machine configurations as confData
     ├── environments/           # Environment presets for various types of machines, optional
+    ├── flake.nix               # Flake entrypoint (recommended)
+    ├── Gemfile                 # Optional Bundler config for tools/bundled-confctl modes
+    ├── Gemfile.lock            # Recommended for Bundler modes
     ├── modules/                # User-defined modules
     │   └── cluster/default.nix # User-defined extensions of `cluster.` options used in `<machine>/module.nix` files
     ├── scripts/                # User-defined scripts
-    ├── swpins/                 # confctl-generated software pins configuration
-    └── shell.nix               # Nix expression for nix-shell
+    ├── shell.nix               # Legacy nix-shell entrypoint
+    └── swpins/                 # confctl-generated software pins configuration
 
 ## Software pins
 Software pins in confctl allow you to use specific revisions of
@@ -133,7 +220,7 @@ or selected machines in the configuration. Or, if needed, custom software pins
 can be configured on selected machines. See below for usage examples.
 
 ## Software pin channels
-Software pin channels are defined in file `confctl/swpins.nix`:
+Software pin channels are defined in file `configs/swpins.nix`:
 
 ```nix
 { config, ... }:
@@ -154,7 +241,7 @@ Software pin channels are defined in file `confctl/swpins.nix`:
           fetchSubmodules = false;
 
           # git reference to use for manual/automated update using
-	  # `confctl swpins channel update`
+          # `confctl swpins channel update`
           update.ref = "refs/heads/nixos-unstable";
 
           # Whether to enable automated updates triggered by `confctl build | deploy`
@@ -163,7 +250,7 @@ Software pin channels are defined in file `confctl/swpins.nix`:
           # If update.auto is true, this determines how frequently will confctl
           # try to update the channel, in seconds
           update.interval = 60*60;
-	};
+        };
       };
     };
 
@@ -175,7 +262,7 @@ Software pin channels are defined in file `confctl/swpins.nix`:
         git-rev = {
           url = "https://github.com/vpsfreecz/vpsadminos";
           update.ref = "refs/heads/staging";
-	  update.auto = true;
+          update.auto = true;
         };
       };
     };
@@ -188,6 +275,12 @@ and how to fetch them. Such configured channels can then be manipulated using
 `confctl`. `confctl` prefetches selected software pins and saves their hashes
 in JSON files in the `swpins/` directory.
 
+In flake-based configurations (using `confctl.lib.mkConfctlOutputs`), channel
+names are provided by the flake `channels` mapping. Machines should select
+channels via `cluster.<name>.inputs.channels` (preferred) and can override the
+role-to-input mapping with `cluster.<name>.inputs.overrides`. Legacy
+`cluster.<name>.swpins.channels` remains supported for non-flake configs.
+
 ```
 # List channels
 $ confctl swpins channel ls
@@ -232,8 +325,11 @@ For example, machine named `my-machine` would be described in
     # This tells confctl whether it is a NixOS or vpsAdminOS machine
     spin = "nixos";
 
-    # Use NixOS unstable channel defined in configs/swpins.nix
-    swpins.channels = [ "nixos-unstable" ];
+    # Flake configs: prefer inputs.channels (channels come from mkConfctlOutputs)
+    inputs.channels = [ "nixos-unstable" ];
+
+    # Legacy configs: use swpins.channels (configs/swpins.nix)
+    # swpins.channels = [ "nixos-unstable" ];
 
     # If the machine name is not a hostname, configure the address to which
     # should confctl deploy it
@@ -262,11 +358,11 @@ Per-machine software pins are configured in the machine's `module.nix` file:
     # Per-machine swpins
     swpins.pins = {
       "pin-name" = {
-          type = "git-rev";
-	  git-rev = {
-            # ...pin definition...
-	  };
-       };
+        type = "git-rev";
+        git-rev = {
+          # ...pin definition...
+        };
+      };
     };
   };
 }
@@ -277,11 +373,12 @@ Instead of `confctl swpins channel` commands, use `confctl swpins cluster`
 to manage configured pins.
 
 ## Nix flakes
-confctl's software pins are an alternative to flakes and flakes are not supported
-by confctl at this time. Software pins are implemented by manipulating the `$NIX_PATH`
-environment variable, which is in conflict with using flakes. confctl is likely
-to be migrated to flakes when the interface will be stabilized. Since the transition
-is going to require a significant effort, there are no plans for it currently.
+confctl can be used from a configuration flake via `confctl.lib.mkConfctlOutputs`.
+In that mode, channel definitions live in the flake `channels` mapping and machines
+select them via `cluster.<name>.inputs.channels`. Per-machine role-to-input overrides
+are done via `cluster.<name>.inputs.overrides`.
+
+`cluster.<name>.swpins.*` and `configs/swpins.nix` are not evaluated in flake mode.
 
 ## Extra module arguments
 Machine configs can use the following extra module arguments:
@@ -293,7 +390,17 @@ Machine configs can use the following extra module arguments:
 - `confMachine` - attrset with information about the machine that is currently
   being built, contains key `name` and all options from
   [machine metadata module](##machine-metadata-and-software-pins)
-- `swpins` - attrset of software pins of the machine that is currently being built
+- `flakeInputs` - flake inputs passed to `mkConfctlOutputs` (excluding `self`)
+- `configurationInfo` - exact source revision and dirty state of the
+  configuration flake when Git metadata is available, exposed as
+  `confctl.configurationInfo` and written to
+  `/etc/confctl/configuration-info.json`
+- `inputs` - attrset of flake input store paths selected for the machine build
+- `swpins` - (legacy configs only) attrset of prefetched software pins of the machine that is currently being built
+- `inputsInfo` - metadata about flake inputs selected for the machine (keys are
+  roles like `nixpkgs`/`vpsadminos`, values include `input`, `url`, `rev`,
+  `shortRev`, `lastModified`), exposed as `confctl.inputsInfo` and written to
+  `/etc/confctl/inputs-info.json`
 
 For example in `cluster/my-machine/config.nix`:
 
@@ -515,3 +622,4 @@ See the [man pages](./man/man8) for more information:
 
 * [confctl(8)](./man/man8/confctl.8.md)
 * [confctl-options.nix(8)](./man/man8/confctl-options.nix.8.md)
+* [Migrating from swpins to flakes](docs/swpins-to-flakes.md)

data/Rakefile

@@ -3,6 +3,7 @@ require 'confctl'
 require 'md2man/rakefile'
 require 'md2man/roff/engine'
 require 'md2man/html/engine'
+require 'rspec/core/rake_task'
 
 # Override markdown engine to add extra parameter
 [Md2Man::Roff, Md2Man::HTML].each do |mod|
@@ -38,3 +39,7 @@ task 'confctl-options' do
     end
   }, 'man/man8/confctl-options.nix.8.md')
 end
+
+desc 'Run RSpec tests'
+RSpec::Core::RakeTask.new(:spec)
+task test: :spec

data/confctl.gemspec

@@ -10,12 +10,30 @@ Gem::Specification.new do |s|
     s.description = 'Nix deployment management tool'
   s.authors     = 'Jakub Skokan'
   s.email       = 'jakub.skokan@vpsfree.cz'
-  s.files       = `git ls-files -z`.split("\x0")
+  files =
+    if File.directory?(File.join(__dir__, '.git'))
+      `git ls-files -z`.split("\x0")
+    else
+      Dir.chdir(__dir__) do
+        Dir.glob('**/*', File::FNM_DOTMATCH).reject do |f|
+          f == '.' || f == '..' ||
+            f.start_with?('.git/') ||
+            f.start_with?('pkg/') ||
+            f.start_with?('tmp/') ||
+            f.start_with?('log/') ||
+            f.start_with?('.bundle/') ||
+            f.start_with?('vendor/') ||
+            f.end_with?('~')
+        end
+      end
+    end
+
+  s.files = files
   s.files      += Dir['man/man?/*.?']
   s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   s.license     = 'GPL-3.0-only'
 
-  s.required_ruby_version = '>= 3.1.0'
+  s.required_ruby_version = '>= 3.3.0'
 
   s.add_dependency 'curses'
   s.add_dependency 'gli', '~> 2.22.0'

data/docs/carrier.md

@@ -47,7 +47,7 @@ Custom build attributes can be created by the user. For example, this is how
 
 ```nix
 # File cluster/nixos/config.nix
-{ config, pkgs, lib, confMachine, swpinsInfo, ... }:
+{ config, pkgs, lib, confMachine, inputsInfo, ... }:
 let
   # machine.json contains metadata about the machine that the carrier uses
   # to assemble the netboot server
@@ -72,11 +72,11 @@ let
     macs = confMachine.netboot.macs;
 
     # Information used by confctl status
-    swpins-info = swpinsInfo;
+    inputs-info = inputsInfo;
   });
 in {
   imports = [
-    <nixpkgs/nixos/modules/installer/netboot/netboot-minimal.nix>
+    "${pkgs.path}/nixos/modules/installer/netboot/netboot-minimal.nix"
   ];
 
   # Define custom build attribute

data/docs/flake-inputs.md

@@ -0,0 +1,159 @@
+# Flake inputs
+
+confctl supports flake-based configuration repositories via `confctl.lib.mkConfctlOutputs`.
+
+In flake configs:
+
+- inputs are normal flake inputs locked in `flake.lock`
+- machines select “channels” via `inputs.channels`
+- machines can override role→input mapping via `inputs.overrides`
+- updates are performed by `confctl inputs ...` (or `nix flake lock --update-input ...`)
+
+This document explains the model and the common workflows.
+
+## Roles, inputs, and channels
+
+A **role** is a named dependency such as:
+
+- `nixpkgs`
+- `vpsadminos`
+- `vpsadmin`
+
+A role is mapped to a **flake input name** via **channels**.
+
+A **channel** is just a name like `production` or `staging` that selects a set of role mappings.
+
+Example:
+
+```nix
+channels = {
+  staging = {
+    nixpkgs = "nixpkgsStable";
+    vpsadminos = "vpsadminosStaging";
+    vpsadmin = "vpsadminStaging";
+  };
+
+  production = {
+    nixpkgs = "nixpkgsStable";
+    vpsadminos = "vpsadminosProduction";
+    vpsadmin = "vpsadminProduction";
+  };
+};
+```
+
+## `mkConfctlOutputs` flake skeleton
+
+A minimal pattern:
+
+```nix
+{
+  description = "my cluster config (confctl flake)";
+
+  inputs = {
+    confctl.url = "github:vpsfreecz/confctl";
+
+    nixpkgsStable.url = "github:NixOS/nixpkgs/nixos-25.11";
+    vpsadminosStaging.url = "github:vpsfreecz/vpsadminos/staging";
+    vpsadminosProduction.url = "github:vpsfreecz/vpsadminos/staging";
+
+    vpsadminStaging = {
+      url = "github:vpsfreecz/vpsadmin/2026-02-19-flakes";
+      inputs.vpsadminos.follows = "vpsadminosStaging";
+    };
+
+    vpsadminProduction = {
+      url = "github:vpsfreecz/vpsadmin/2026-02-19-flakes";
+      inputs.vpsadminos.follows = "vpsadminosProduction";
+    };
+  };
+
+  outputs = inputs@{ self, confctl, ... }:
+    let
+      channels = {
+        staging = {
+          nixpkgs = "nixpkgsStable";
+          vpsadminos = "vpsadminosStaging";
+          vpsadmin = "vpsadminStaging";
+        };
+
+        production = {
+          nixpkgs = "nixpkgsStable";
+          vpsadminos = "vpsadminosProduction";
+          vpsadmin = "vpsadminProduction";
+        };
+      };
+    in
+    {
+      confctl = confctl.lib.mkConfctlOutputs {
+        confDir = ./.;
+        inherit inputs channels;
+      };
+
+      # Optional: configuration-repo dev shell
+      devShells.x86_64-linux.default = confctl.lib.mkConfigDevShell {
+        system = "x86_64-linux";
+        mode = "minimal";
+      };
+    };
+}
+```
+
+## Selecting channels on a machine
+
+In machine metadata (typically `cluster/<name>/module.nix`), choose channels:
+
+```nix
+{ ... }:
+{
+  cluster."my-machine" = {
+    spin = "nixos";
+    inputs.channels = [ "production" ];
+  };
+}
+```
+
+Multiple channels can be combined; later channels can override roles from earlier ones.
+
+## Per-machine overrides
+
+To override one role for a single machine:
+
+```nix
+cluster."my-machine".inputs.overrides.nixpkgs = "nixpkgsMunin";
+```
+
+Use this sparingly. The default model is: select channels, update channels.
+
+## Updating inputs
+
+Inputs are flake inputs in `flake.lock`.
+
+Common commands:
+
+```bash
+confctl inputs ls
+confctl inputs update --commit <input...>
+
+confctl inputs channel ls
+confctl inputs channel update --commit '{production,staging}' vpsadminos
+
+confctl inputs machine update --commit <machine> nixpkgs
+```
+
+- `--no-changelog` disables including `git log --oneline old..new` in the commit message.
+- `--downgrade` is useful when you intentionally move to an older revision and still want the changelog direction to make sense.
+
+## Nested inputs and `follows`
+
+If input **A** depends on input **B** and you want the *top-level flake* to decide the revision of **B**, use `follows`.
+
+Example (vpsadmin → vpsadminos):
+
+```nix
+inputs.vpsadminStaging = {
+  url = "github:vpsfreecz/vpsadmin/2026-02-19-flakes";
+  inputs.vpsadminos.follows = "vpsadminosStaging";
+};
+```
+
+Because `follows` is per-input-name, you typically need separate inputs per environment (staging vs production) to pin independently.