Add tutorials #1026
Add tutorials #1026
Conversation
There was a problem hiding this comment.
Didn't look at the deployment one yet. Please make a separate PRs for each, so we don't have to block things on each other and merge once something is done.
What's currently missing generally are explicit prerequisites. Otherwise we'll easily run people into surprise obstacles. Having those prerequisites will also inform us on what we need to go through to call a tutorial complete.
Another thought on the caching tutorial: Maybe it would make sense to orient everything around SSH instead? Then we'd have overall fewer moving parts: the deployment will already talk about setting up SSH, we'll set up signing keys only for distributed builds, and then enabling the cache will neither need nix-serve, nor any of the HTTPS stuff (including the hard requirement for a DNS domain), nor the signing keys, and we re-use the knowledge to handle SSH keys. Is there any notable performance difference between the HTTP and SSH stores?
|
|
||
| ```shell-session | ||
| mkdir /var/secrets | ||
| cd /var/secrets | ||
| nix-store --generate-binary-cache-key cache.example.com cache-private-key.pem cache-public-key.pem | ||
| ``` |
There was a problem hiding this comment.
Secrets provisioning is too much of rabbit hole for now, but given that we need to distribute the public key to clients, it may make sense to generate the secrets on the current machine and push them to the cache. (The current text doesn't even say that you have to run this on the cache machine.) That would be more ceremony for the tutorial, as we'd also need to instruct users how to set up an SSH keypair -- therefore I don't really care how we go about it, but there needs to be clear instructions how to get the right keys to the right place, as otherwise this will be a substantial point of friction since currently it is nowhere shown how to do these things.
I think scp-ing or rsync-ing from the local machine is the most reasonable thing to do, but that would require setting up the machine configuration first.
|
|
||
| `cache-private-key.pem` will be used by the binary cache daemon to sign the binaries as they are served. | ||
| It should only be accessible for the `nix-serve` daemon. | ||
| (We will set the access rights accordingly as soon as this user exists.) |
There was a problem hiding this comment.
This weird ordering indicates that doing the configuration first and then generating and distributing the keys is more sensible.
| ``` | ||
|
|
||
| `cache-private-key.pem` will be used by the binary cache daemon to sign the binaries as they are served. | ||
| It should only be accessible for the `nix-serve` daemon. |
There was a problem hiding this comment.
We're talking about nix-serve without having introduced anything about it. There should be at least a sentence about what that software does, and a link to the source. (But this is for after figuring out the final order of operations in the tutorial.)
| - [Settings for Distributed Builds in the Nix Manual][distributed-builds-nix] | ||
|
|
||
| [nix-serve-options]: https://search.nixos.org/options?query=services.nix-serve | ||
| [distributed-builds-nix]: https://nix.dev/manual/nix/2.18/advanced-topics/distributed-builds |
There was a problem hiding this comment.
The current version is here: https://nix.dev/manual/nix/2.24/advanced-topics/distributed-builds
But that page should essentially be replaced by this very tutorial and I'll add a redirect once we're done. The relevant reference documentation is here: https://nix.dev/manual/nix/2.24/command-ref/conf-file#conf-builders
|
|
||
| ## Set up distributed builds | ||
|
|
||
| On the *local machine*, add the file `/etc/nixos/distributed-builds.nix`: |
There was a problem hiding this comment.
We also need instructions for vanilla Nix here. NixOS is more of an investment, and we must assume that about half of new users will try Nix on their existing Arch or Ubuntu system. In other tutorials we use a highlight box to set off the NixOS case.
There was a problem hiding this comment.
Earlier when we chatted directly, I explicitly asked about this to understand the scope of the tasks. Your answer was that we're only explaining it for NixOS for now.
There was a problem hiding this comment.
Ah maybe that was a misunderstanding, I thought that was about where the cache service would run. Configuring distributed builds amounts to setting one or two lines in nix.conf and pointing readers to the respective parts in the Nix manual for the details.
There was a problem hiding this comment.
Most of the comments from this set are fairly low-level. To make progress in the big picture, please split the deployment tutorial into a separate PR so we can finalize that and then see which pre-existing information (such as a working SSH setup) we can lean on in the follow-ups to cut them down as far as possible.
| # nixos-rebuild switch | ||
| ``` | ||
|
|
||
| ### On Non-NixOS systems |
There was a problem hiding this comment.
This should be the default step. Please search for NixOS in the source for an example how to make a highlighted box for the NixOS case.
Also, "non-NixOS" is a forbidden word here, because it purports a NixOS-centric worldview which is not legitimate in a beginner setting.
| ``` | ||
|
|
||
| This configuration module enables distributed builds and adds the remote builder. | ||
| Replace `system` with the correct architecture if yours differs. |
There was a problem hiding this comment.
This needs a link to (or concrete) instructions how to find out your system string.
| This configuration module enables distributed builds and adds the remote builder. | ||
| Replace `system` with the correct architecture if yours differs. |
There was a problem hiding this comment.
Actually, this explanation is misleading. The config sets up a remote builder that will take derivations for the given system type and features. There's pretty extensive documentation in the Nix manual on what that means, but the concise blurb here should already be clear about the semantics.
We can't afford to be vague or handwave these core aspects in tutorials, as that has the potential to confuse people for a long time until they decide to investigate in reference documentation why they have run into a mismatch between their mental model and reality. This is also why the pattern is always to link to sufficiently mature reference docs for such non-trivial concepts right from the place where they are introduced.
|
|
||
| If you like, you can add more options to the configuration now or after the initial deployment. | ||
|
|
||
| ## Deploy the system |
There was a problem hiding this comment.
This is missing the step of test-booting the config using the installTest (IIRC) attribute provided by the disko module. Once you want to fiddle with the disk layout it's super easy to break it, since there's currently no viable reference documentation for disko
| } | ||
| ``` | ||
|
|
||
| This disk layout describes a single disk with a boot and ESP partition and a root file system that takes all available space. |
There was a problem hiding this comment.
Add a pointer to the upstream examples collection, which is currently a stand-in for proper docs
|
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/unattended-install-via-usb-stick/51068/2 |
|
Follow-up: #1038 |
This pull request aims to close tickets #1012, #1013, #1014