···44description: How to apply a node with wire.
55---
6677-# {{ $frontmatter.title }}
77+# Apply your Config
8899{{ $frontmatter.description }}
1010···28282929Which will `switch` to each node's NixOS system in your hive and push
3030secrets (the equivalent to `nixos-rebuild`'s `nixos-rebuild switch`).
3131-3232-::: details Apply Goal Flowchart
3333-The following is an illustrative flowchart of how each step in the apply execution is ran.
3434-3535-Depending on the specific goal certain steps will not run, for example the
3636-Switch to Configuration step will never run if the goal is `build`.
3737-3838-```mermaid
3939-flowchart TD
4040- A(Test Connection) --> |IP / Hostname| B(Push Keys)
4141-4242- C(Evaluate NixOS System)
4343-4444- B --> C
4545- C -->|.drv Path| local
4646- C -->|.drv Path| remote
4747-4848- subgraph remote[Remote Node]
4949- D(Push To Node)
5050- D --> E(Build NixOS System)
5151- E -->|Built System| H(Push To Node)
5252- end
5353-5454- subgraph local[Local Node]
5555- direction RL
5656- G(Build NixOS System Locally)
5757- end
5858-5959- G --> F(Switch To Configuration)
6060- H --> F
6161-```
6262-6363-:::
64316532## Apply goals
6633
+1-1
doc/guides/flakes/nixos-rebuild.md
···44description: How to combine outputs.nixosConfigurations with outputs.wire
55---
6677-# {{ $frontmatter.title }}
77+# Keep Using nixos-rebuild
8899{{ $frontmatter.description }}
1010
+1-1
doc/guides/flakes/overview.md
···44description: How to output a hive from a flake.
55---
6677-# {{ $frontmatter.title }}
77+# Use Flakes
8899{{ $frontmatter.description }}
1010
···44description: How to install wire tool.
55---
6677-# {{ $frontmatter.title }}
77+# Install wire
8899{{ $frontmatter.description }}
1010···19192020## Binary Cache
21212222-You should enable the [garnix binary cache](https://garnix.io/docs/caching).
2222+You should enable the [garnix binary cache](https://garnix.io/docs/caching)
2323+*before* continuing otherwise you will be compiling from source:
2424+2525+::: code-group
2626+<<< @/snippets/tutorial/cache.conf [nix.conf]
2727+<<< @/snippets/tutorial/cache.nix [configuration.nix]
2828+:::
23292430## Installation through flakes
2531···50565157Then, use this pinned version of wire for both your `hive.nix` and `shell.nix`:
52585353-::: code-group
5459<<< @/snippets/guides/installation/shell.nix{8} [shell.nix]
5560<<< @/snippets/guides/installation/hive.nix [hive.nix]
5656-:::
+1-1
doc/guides/keys.md
···44description: Manage keys, secrets, files, and other out-of-store paths with wire Tool.
55---
6677-# {{ $frontmatter.title }}
77+# Manage Secrets
8899{{ $frontmatter.description }}
1010
+1-1
doc/guides/migrate.md
···44description: How-to migrate from other tools to wire tool.
55---
6677-# {{ $frontmatter.title }}
77+# Migrate to wire
8899{{ $frontmatter.description }}
1010
+14-15
doc/guides/non-root-user.md
···44description: Deploy without root permissions with wire.
55---
6677-# {{ $frontmatter.title }}
77+# Use a non-root user
8899{{ $frontmatter.description }}
10101111## Deploying User Requirements
12121313-If your selected deployment user does not fit the following requirements, the
1414-deployment commands will likely fail with an error:
1313+For deployment commands to succeed, the user defined in `deployment.target.user` must meet the following criteria:
1414+1515+1. Essential Config
1616+1717+- **Sudo Access**: The user must be `wheel` (A sudo user)
1818+- **SSH Key Authentication**: The user must be authenticated through SSH keys,
1919+ and password-based SSH auth is not supported.
2020+2121+ **Why?** Wire can prompt you for your `sudo` password, but not your `ssh` password.
15221616-| `deployment.target.user` has/is... | ❌ Will Not Work | 🟧 Deploys w/o Keys | ✅ Deploys w/ Keys |
1717-| :--------------------------------- | :--------------: | :-----------------: | :----------------: |
1818-| In `wheel` (Sudo User) | No | Yes | Yes |
1919-| Has Non-Interactive SSH Auth | - | Yes | Yes |
2020-| A Trusted User | - | No | Yes |
2323+2. Deploying with Secrets
21242222-When using a non-trusted user, `wire apply` will likely fail if the deploying user is
2323-not trusted, see [Manage Secrets - Prerequisites](/guides/keys.html#prerequisites).
2525+- **Trusted User**: The user must be listed in the `trusted-users` nix config.
24262525-- "In `wheel`" here meaning a sudoer, whether it be `root` or not.
2626-- "Non-interactive SSH Auth" here most likely meaning an SSH key, anything that
2727- does not require keyboard input in the terminal.
2727+ If the user is not trusted, wire will fail in the key deployment stage.
28282929-To put it simply, wire can currently prompt for your password on `sudo`,
3030-but not `ssh`.
2929+For setting up a trusted user, see [Manage Secrets - Prerequisites](/guides/keys.html#prerequisites).
31303231## Changing the user
3332
+1-1
doc/guides/parallelism.md
···44description: How to use parallelism with wire Tool.
55---
6677-# {{ $frontmatter.title }}
77+# Use Parallelism
8899{{ $frontmatter.description }}
1010
+1-1
doc/guides/targeting.md
···44description: Tags, nodes, and how to target them with wire Tool.
55---
6677-# {{ $frontmatter.title }}
77+# Target Nodes
8899{{ $frontmatter.description }}
1010
+21-25
doc/guides/writing-a-hive.md
···33title: Write a Hive
44---
5566-# {{ $frontmatter.title }}
66+# Write a Hive
7788## Anatomy of a Hive
99···1111following layout:
12121313```nix
1414-# `meta`
1515-# type: attrset
1616-meta = {
1717- # `meta.nixpkgs` tells wire how to get nixpkgs.
1818- # type: "A path or an instance of nixpkgs."
1919- nixpkgs = <nixpkgs>;
2020-2121- # `meta.specialArgs` are specialArgs to pass to each node & default
1414+wire.makeHive {
1515+ # `meta`
2216 # type: attrset
2323- specialArgs = { };
1717+ meta = {
1818+ # `meta.nixpkgs` tells wire how to get nixpkgs.
1919+ # type: "A path or an instance of nixpkgs."
2020+ nixpkgs = <nixpkgs>;
24212525- # `meta.nodeNixpkgs` lets you override nixpkgs per-node.
2626- # type: attrset of "A path or an instance of nixpkgs."
2727- nodeNixpkgs: = { };
2828-};
2222+ # `meta.specialArgs` are specialArgs to pass to each node & default
2323+ # type: attrset
2424+ specialArgs = { };
29253030-# `defaults` is a module applied to every node
3131-# type: NixOS Module
3232-defaults = { ... }: { };
2626+ # `meta.nodeNixpkgs` lets you override nixpkgs per-node.
2727+ # type: attrset of "A path or an instance of nixpkgs."
2828+ nodeNixpkgs: = { };
2929+ };
33303434-# Any other attributes are nodes.
3131+ # `defaults` is a module applied to every node
3232+ # type: NixOS Module
3333+ defaults = { ... }: { };
3434+3535+ # Any other attributes are nodes.
3636+ <node-name> = { ... }: { };
3737+}
3538```
36393740### `<node-name>`
···52555356At the top level of a hive wire reserves the `defaults` attribute. It's applied
5457to every node.
5555-5656-::: warning
5757-5858-`defaults` must not rely on modules that a node imports, but a
5959-node may rely on modules that default imports.
6060-6161-:::
62586359## Example
6460
···44description: In this tutorial we will create and deploy a wire Hive.
55---
6677-# {{ $frontmatter.title }}
77+# wire Tutorial Overview
8899wire is a tool to deploy NixOS systems. Its usage is inspired by [colmena](https://colmena.cli.rs/). In many places it's configuration attempts to remain a superset[^1] of colmena, however it is **not** a fork.
1010···28282929</div>
30303131-## Why wire?
3232-3333-### Features
3131+## What features does wire have?
34323533| Features | wire | Colmena |
3634| ------------------------------------------------------------- | ------------------ | ------------------ |
···5048[^3]: See https://github.com/zhaofengli/colmena/issues/120
51495250[^4]: wire lacks an equivalent to `colmena exec`.
5353-5454-### Speed
5555-5656-wire is about >2x faster than colmena deploying [identical large
5757-hives](https://github.com/mrshmllow/wire/blob/trunk/bench/run.nix).
5858-5959-| Command | Mean [s] | Min [s] | Max [s] | Relative |
6060-| :--------------- | -------: | ------: | ------: | -------: |
6161-| `wire@HEAD` | 185.075 | 185.075 | 185.075 | 1.00 |
6262-| `colmena@pinned` | 343.075 | 343.075 | 343.075 | 1.85 |
+1-1
doc/tutorial/part-one/basic-hive.md
···44description: Creating a basic hive and deploying changes to the virtual machine.
55---
6677-# {{ $frontmatter.title }}
77+# Basic Hive & Deployment
8899{{ $frontmatter.description }}
1010
+7-2
doc/tutorial/part-one/nix-setup.md
···44description: Installing npins, nix, and enabling the binary cache.
55---
6677-# {{ $frontmatter.title }}
77+# Nix Setup
8899{{ $frontmatter.description }}
1010···3232cache](https://wiki.nixos.org/wiki/Binary_Cache).
33333434You must enable the [garnix binary cache](https://garnix.io/docs/caching) or you
3535-will be compiling everything from source.
3535+will be compiling everything from source:
3636+3737+::: code-group
3838+<<< @/snippets/tutorial/cache.conf [nix.conf]
3939+<<< @/snippets/tutorial/cache.nix [configuration.nix]
4040+:::
+1-1
doc/tutorial/part-one/repo-setup.md
···44description: Adding npins sources and a nix development shell.
55---
6677-# {{ $frontmatter.title }}
77+# Preparing Repo & Shell
8899{{ $frontmatter.description }}
1010
+1-1
doc/tutorial/part-one/vm-setup.md
···44description: Creating a NixOS virtual machine to use as a deployment target.
55---
6677-# {{ $frontmatter.title }}
77+# Creating a Virtual Machine
8899{{ $frontmatter.description }}
1010