···1616│ └── key_agent
1717│ └── Rust binary ran on a target node. recieves key file bytes and metadata w/ protobuf over SSH stdin
1818├── doc
1919-│ └── an [mdBook](https://rust-lang.github.io/mdBook/)
1919+│ └── a [vitepress](https://vitepress.dev/) site
2020├── runtime
2121│ └── Nix files used during runtime to evaluate nodes
2222├── intergration-testing
···11+# wire docs
22+33+`reference/{cli,module}.nix` are filled in during a nix build w/ nixos module docs generation and clap. Read `package.nix`'s patchPhase for the details.
44+55+## Develop
66+77+```sh
88+pnpm install
99+pnpm run dev
1010+```
1111+1212+## Build
1313+1414+```sh
1515+nix build .#docs
1616+1717+# or
1818+1919+pnpm install
2020+pnpm run build
2121+```
2222+2323+The build will be found in `result/` or `.vitepress/dist` respectively.
···11+# What is Wire?
22+33+Wire is a tool to deploy NixOS systems. Its configuration is a superset[^1] of [colmena](https://colmena.cli.rs/), however it is **not** a fork.
44+55+[^1]: Any colmena configuration will continue to work with wire, but wire has additional ergonomic changes you can take advantage of.
66+77+::: warning
88+Wire is alpha software, please use at your own risk. Many features listed in this documentation may not be complete / implemented.
99+:::
1010+1111+<div class="tip custom-block" style="padding-top: 8px">
1212+1313+Ready? Skip to the [Quickstart](./getting-started).
1414+1515+</div>
1616+1717+## Why Wire?
1818+1919+::: info
2020+The following is the goal for a stable release and not fully implemented.
2121+:::
2222+2323+| Features | Wire | Colmena |
2424+| -------------- | ------------- | -------- |
2525+| Secret Management | :white_check_mark: | :white_check_mark: |
2626+| Parallel Evaluation | :white_check_mark: | [Experimental](https://colmena.cli.rs/unstable/features/parallelism.html#parallel-evaluation-experimental) |
2727+| Node Tagging | :white_check_mark: | :white_check_mark: |
2828+| `jq` pipeline support | :white_check_mark: | :x:[^2] |
2929+| Magic Rollback | :white_check_mark: (Planned) | :x: |
3030+3131+[^2]: You need to write custom nix code to use Colmena hive metadata inside environments like CI pipelines, bash scripting, etc., which requires a knowledge of its internals.
+25
doc/index.md
···11+---
22+# https://vitepress.dev/reference/default-theme-home-page
33+layout: home
44+55+hero:
66+ name: "wire"
77+ text: "a tool to deploy nixos systems"
88+ # tagline: My great project tagline
99+ actions:
1010+ - theme: brand
1111+ text: Read Guide
1212+ link: /guide/wire
1313+ - theme: alt
1414+ text: Reference
1515+ link: /reference/cli
1616+1717+features:
1818+ - title: Parallelism
1919+ details: Build and deploy many nodes at once
2020+ - title: Secret management
2121+ details: Fast & Unopinionated secret management
2222+ - title: Node Tagging & CI Friendly
2323+ details: Pipe data through jq
2424+---
2525+
···11-# Creating a hive
22-33-A "hive" is a collection of nodes. Each node has tags, keys, and options that define how to connect to it.
-82
doc/src/creating-a-hive/flake.md
···11-# With Flakes
22-33-Deploying nodes from a flake is as simple as adding a `colmena` attribute to your flake outputs.
44-55-Wire will merge nixos options in `nixosConfigurations.${nodeName}` and `colmena.${nodeName}` to create the configuration it deploys. This means you can continue to use `nixos-rebuild` to deploy your configurations alongside wire.
66-77-You don't need to create a `nixosConfigurations` attribute for your nodes if you don't want to.
88-99-Every node recieves its name and a list of all other nodes through specialArgs.
1010-1111-```nix
1212-# flake.nix
1313-{
1414- # wire will automatically use the nixpkgs input.
1515- # change `colmena.meta.nixpkgs` if you want to use a different nixpkgs
1616- inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
1717-1818- outputs = {nixpkgs, ...}: {
1919- nixosConfigurations.node-a = nixpkgs.lib.nixosSystem {
2020- system = "x86_64-linux";
2121- modules = [
2222- ./node-a/configuration.nix
2323- ];
2424- };
2525-2626- colmena = {
2727- defaults = {
2828- # name of node default is being applied to
2929- node,
3030- # list of all nodes
3131- nodes,
3232- pkgs,
3333- ...
3434- }: {
3535- environment.systemPackages = with pkgs; [
3636- vim
3737- ];
3838- };
3939-4040- node-a = {
4141- # name of this node
4242- name,
4343- # list of all nodes
4444- nodes,
4545- pkgs,
4646- ...
4747- }: {
4848- deployment.target = {
4949- # host defaults to the name of the node
5050- host = "node-a";
5151- # if you use a different user, it must be wheel
5252- user = "root";
5353- };
5454-5555- # wire specific options are only valid here
5656- # for example, adding keys
5757- deployment.keys."key.env" = {
5858- destDir = "/etc/keys/";
5959- source = [
6060- "gpg"
6161- "--decrypt"
6262- ./secrets/key.env.gpg
6363- ];
6464- };
6565-6666- # other module options are valid here
6767- system.stateVersion = "24.11";
6868- };
6969-7070- # nodes don't have to be a function
7171- # and they don't have to be in `nixosConfigurations`
7272- node-b = {
7373- deployment.target = {
7474- # ...
7575- };
7676-7777- imports = [./node-b/configuration.nix];
7878- };
7979- };
8080- };
8181-}
8282-```
-68
doc/src/creating-a-hive/hive.md
···11-# Without Flakes
22-33-Create a `hive.nix` file, which is equivalent to a flake's `outputs.colmena`.
44-You must manually specify where nixpkgs comes from when using `hive.nix`.
55-66-Every node recieves its name and a list of all other nodes through specialArgs.
77-88-```nix
99-# hive.nix
1010-{
1111- # you must specify where nixpkgs comes from when using hive.nix
1212- meta.nixpkgs = <nixpkgs>;
1313-1414- defaults = {
1515- # name of node default is being applied to
1616- node,
1717- # list of all nodes
1818- nodes,
1919- pkgs,
2020- ...
2121- }: {
2222- environment.systemPackages = with pkgs; [
2323- vim
2424- ];
2525- };
2626-2727- node-a = {
2828- # name of this node
2929- name,
3030- # list of all nodes
3131- nodes,
3232- pkgs,
3333- ...
3434- }: {
3535- deployment.target = {
3636- # host defaults to the name of the node
3737- host = "node-a";
3838- # if you use a different user, it must be wheel
3939- user = "root";
4040- };
4141-4242- imports = [./node-a/configuration.nix];
4343-4444- # wire specific options are valid here
4545- # for example, adding keys
4646- deployment.keys."key.env" = {
4747- destDir = "/etc/keys/";
4848- source = [
4949- "gpg"
5050- "--decrypt"
5151- ./secrets/key.env.gpg
5252- ];
5353- };
5454-5555- # other module options are valid here
5656- system.stateVersion = "24.11";
5757- };
5858-5959- # nodes don't have to be a function
6060- node-b = {
6161- deployment.target = {
6262- # ...
6363- };
6464-6565- imports = [./node-b/configuration.nix];
6666- };
6767-}
6868-```
···11-# Parrallelism
22-33-Wire selects nodes to deploy and performs the specified goal for each node in parallel.
44-55-Use `--parallel` to limit the number of nodes that are deployed in parallel. It defaults to 10 nodes at a time.
···11-# Tagging
22-33-You can assign tags to nodes, and target nodes by tags. Use `--on @TAG` to reference them.
44-55-```nix
66-{
77- node-a = {
88- deployment = {
99- tags = ["arm" "native"];
1010- };
1111- };
1212-}
1313-```
1414-1515-```
1616-wire apply --on @arm
1717-```
-13
doc/src/intro.md
···11-# Intro
22-33-Wire is a tool to deploy nixos systems. Its configuration is a superset of [colmena](https://colmena.cli.rs/), however it is not a fork.
44-55-Any colmena configuration will continue to work with wire, but wire has additional ergonomic changes you can take advantage of.
66-77-## Features
88-99-- Keys & Secrets
1010-- Parrallel deployment & evaluation
1111-- Node tagging
1212-- CI Friendly
1313- - Pipe hive metadata to `jq`