mirror of
https://github.com/divnix/digga.git
synced 2024-12-23 08:02:21 +03:00
Merge pull request #477 from divnix/remove-bud
remove bud and misleading onboarding docs
This commit is contained in:
chris montgomery
GitHub
commit
8d50be0910
@ -3,8 +3,6 @@
|
||||
- [Introduction](../README.md)
|
||||
- [Quick Start](./start/index.md)
|
||||
- [ISO](./start/iso.md)
|
||||
- [Bootstrapping](./start/bootstrapping.md)
|
||||
- [From NixOS](./start/from-nixos.md)
|
||||
- [Key Concepts](./concepts/index.md)
|
||||
- [Hosts](./concepts/hosts.md)
|
||||
- [Overrides](./concepts/overrides.md)
|
||||
@ -18,8 +16,6 @@
|
||||
- [Concerns]()
|
||||
- [Secrets](./secrets.md)
|
||||
- [Tests](./tests.md)
|
||||
- [Helper Script – `bud`](./bud/index.md)
|
||||
- [get](./bud/get.md)
|
||||
- [Integrations](./integrations/index.md)
|
||||
- [Cachix](./integrations/cachix.md)
|
||||
- [Deploy RS](./integrations/deploy.md)
|
||||
|
||||
@ -1,10 +0,0 @@
|
||||
# get
|
||||
The `get` subcommand is useful for getting a bare copy of devos without the
|
||||
git history.
|
||||
|
||||
## Usage
|
||||
```sh
|
||||
bud get DEST-DIR
|
||||
```
|
||||
|
||||
If DEST-DIR is ommitted, it defaults to _./devos_.
|
||||
@ -1,24 +0,0 @@
|
||||
# [`bud`][bud] command
|
||||
The template incudes a convenient script for managing your system called [`bud`][bud].
|
||||
|
||||
It is a portable and highly composable system control tool that work anywhere on your host
|
||||
or in the flake's devshell.
|
||||
|
||||
Although it comes with some predefined standard helpers,
|
||||
it is very extensible and you are encouraged to write your own script snippets
|
||||
to ease your workflows. An example is the bud module for a `get` command that
|
||||
comes included with `devos`.
|
||||
|
||||
While writing scripts you can convenientely access smart environment variables
|
||||
that can tell the current architecture, user or host name, among others, regardless
|
||||
wether you invoke `bud` within the devshell or as the system-wide installed `bud`.
|
||||
|
||||
For details, please review the [bud repo][bud].
|
||||
|
||||
## Usage
|
||||
```sh
|
||||
bud help
|
||||
```
|
||||
|
||||
|
||||
[bud]: https://github.com/divnix/bud
|
||||
@ -8,8 +8,7 @@
|
||||
Users are a special case of [profiles](profiles.md) that define system
|
||||
users and [home-manager][home-manager] configurations. For your convenience,
|
||||
home manager is wired in by default so all you have to worry about is declaring
|
||||
your users. For a fully fleshed out example, check out the developers personal
|
||||
[branch](https://github.com/divnix/devos/tree/nrd/users/nrd/default.nix).
|
||||
your users.
|
||||
|
||||
## Basic Usage
|
||||
`users/myuser/default.nix`:
|
||||
@ -49,22 +48,11 @@ argument that gets passed to your home-manager users.
|
||||
|
||||
## External Usage
|
||||
You can easily use the defined home-manager configurations outside of NixOS
|
||||
using the `homeConfigurations` flake output. The [bud](../bud/index.md) helper
|
||||
script makes this even easier.
|
||||
using the `homeConfigurations` flake output.
|
||||
|
||||
This is great for keeping your environment consistent across Unix systems,
|
||||
including OSX.
|
||||
This is great for keeping your environment consistent across Unix-like systems,
|
||||
including macOS.
|
||||
|
||||
### From within the projects devshell:
|
||||
```sh
|
||||
# builds the nixos user defined in the NixOS host
|
||||
bud home NixOS nixos
|
||||
|
||||
# build and activate
|
||||
bud home NixOS nixos switch
|
||||
```
|
||||
|
||||
### Manually from outside the project:
|
||||
```sh
|
||||
# build
|
||||
nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPackage"
|
||||
@ -74,5 +62,5 @@ nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPac
|
||||
```
|
||||
|
||||
[home-manager]: https://nix-community.github.io/home-manager
|
||||
[modules-list]: https://github.com/divnix/devos/tree/main/users/modules/module-list.nix
|
||||
[modules-list]: https://github.com/divnix/digga/tree/main/users/modules/module-list.nix
|
||||
[portableuser]: https://digga.divnix.com/api-reference-home.html#homeusers
|
||||
|
||||
@ -1,102 +0,0 @@
|
||||
# Bootstrapping
|
||||
|
||||
This will help you boostrap a bare host with the help of the
|
||||
[bespoke iso](./iso.md) live installer.
|
||||
|
||||
_Note: nothing prevents you from remotely executing the boostrapping
|
||||
process. See below._
|
||||
|
||||
Once your target host has booted into the live iso, you need to partition
|
||||
and format your disk according to the [official manual][manual].
|
||||
|
||||
## Mount partitions
|
||||
|
||||
Then properly mount the formatted partitions at `/mnt`, so that you can
|
||||
install your system to those new partitions.
|
||||
|
||||
Mount `nixos` partition to `/mnt` and — for UEFI — `boot`
|
||||
partition to `/mnt/boot`:
|
||||
|
||||
```console
|
||||
$ mount /dev/disk/by-label/nixos /mnt
|
||||
$ mkdir -p /mnt/boot && mount /dev/disk/by-label/boot /mnt/boot # UEFI only
|
||||
$ swapon /dev/disk/by-label/swap
|
||||
```
|
||||
|
||||
Add some extra space to the store. In the iso, it's running on a tmpfs
|
||||
off your RAM:
|
||||
```console
|
||||
$ mkdir -p /mnt/tmpstore/{work,store}
|
||||
$ mount -t overlay overlay -olowerdir=/nix/store,upperdir=/mnt/tmpstore/store,workdir=/mnt/tmpstore/work /nix/store
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
Install off of a copy of devos from the time the iso was built:
|
||||
|
||||
```console
|
||||
$ cd /iso/devos
|
||||
$ nixos-install --flake .#NixOS
|
||||
```
|
||||
|
||||
## Notes of interest
|
||||
|
||||
### Remote access to the live installer
|
||||
|
||||
The iso live installer comes preconfigured with a network configuration
|
||||
which announces it's hostname via [MulticastDNS][mDNS] as `hostname.local`,
|
||||
that is `bootstrap.local` in the [iso example](./iso).
|
||||
|
||||
In the rare case that [MulticastDNS][mDNS] is not availabe or turned off
|
||||
in your network, there is a static link-local IPv6 address configured to
|
||||
`fe80::47`(mnemonic from the letter's position in the english alphabet:
|
||||
`n=14 i=9 x=24; 47 = n+i+x`).
|
||||
|
||||
Provided that you have added your public key to the authorized keys of the
|
||||
`root` user _(hint: [`deploy-rs`](../integrations/deploy.md) needs passwordless
|
||||
sudo access)_:
|
||||
|
||||
```nix
|
||||
{ ... }:
|
||||
{
|
||||
users.users.root.openssh.authorizedKeys.keyFiles = [
|
||||
../secrets/path/to/key.pub
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
You can then ssh into the live installer through one of the
|
||||
following options:
|
||||
|
||||
```console
|
||||
ssh root@bootstrap.local
|
||||
|
||||
ssh root@fe80::47%eno1 # where eno1 is your network interface on which you are linked to the target
|
||||
```
|
||||
|
||||
_Note: the [static link-local IPv6 address][staticLLA] and [MulticastDNS][mDNS] is only
|
||||
configured on the live installer. If you wish to enable [MulticastDNS][mDNS]
|
||||
for your environment, you ought to configure that in a regular [profile](../concepts/profiles.md)._
|
||||
|
||||
### EUI-64 LLA & Host Identity
|
||||
|
||||
The iso's IPv6 Link Local Address (LLA) is configured with a static 64-bit Extended
|
||||
Unique Identifiers (EUI-64) that is derived from the host interface's Message
|
||||
Authentication Code (MAC) address.
|
||||
|
||||
After a little while (a few seconds), you can remotely discover this unique and host
|
||||
specific address over [NDP][NDP] for example with:
|
||||
|
||||
```console
|
||||
ip -6 neigh show # also shows fe80::47
|
||||
```
|
||||
|
||||
***This LLA is stable for the host, unless you need to swap that particular network card.***
|
||||
Under this reservation, though, you may use this EUI-64 to wire up a specific
|
||||
(cryptographic) host identity.
|
||||
|
||||
|
||||
[manual]: https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning
|
||||
[mDNS]: https://en.wikipedia.org/wiki/Multicast_DNS
|
||||
[NDP]: https://en.wikipedia.org/wiki/Neighbor_Discovery_Protocol
|
||||
[staticLLA]: https://tools.ietf.org/html/rfc7404
|
||||
@ -1,57 +0,0 @@
|
||||
# From NixOS
|
||||
|
||||
## Generate Configuration
|
||||
Assuming you're happy with your existing partition layout, you can generate a
|
||||
basic NixOS configuration for your system using:
|
||||
```sh
|
||||
bud up
|
||||
```
|
||||
|
||||
This will make a new folder `hosts/$(hostname)`, which you can edit to
|
||||
your liking.
|
||||
|
||||
You must then add a host to `nixos.hosts` in flake.nix:
|
||||
```nix
|
||||
{
|
||||
# ...
|
||||
nixos = {
|
||||
hosts = {
|
||||
/* set host specific properties here */
|
||||
NixOS = { };
|
||||
$(hostname) = { };
|
||||
};
|
||||
};
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for
|
||||
your region. Keep in mind that `networking.hostName` will be automatically
|
||||
set to the name of your host;
|
||||
|
||||
Now might be a good time to read the docs on [suites](../concepts/suites.md) and
|
||||
[profiles](../concepts/profiles.md) and add or create any that you need.
|
||||
|
||||
> ##### _Note:_
|
||||
> While the `up` sub-command is provided as a convenience to quickly set up and
|
||||
> install a "fresh" NixOS system on current hardware, committing these files is
|
||||
> discouraged.
|
||||
>
|
||||
> They are placed in the git staging area automatically because they would be
|
||||
> invisible to the flake otherwise, but it is best to move what you need from
|
||||
> them directly into a host module of your own making, and commit that instead.
|
||||
# Installation
|
||||
|
||||
Once you're ready to deploy `hosts/$(hostname)`:
|
||||
```sh
|
||||
bud rebuild $(hostname) switch
|
||||
```
|
||||
|
||||
|
||||
This calls `nixos-rebuild` with sudo to build and install your configuration.
|
||||
|
||||
> ##### _Notes:_
|
||||
> - Instead of `switch`, you can pass `build`, `test`, `boot`, etc just as with
|
||||
> `nixos-rebuild`.
|
||||
|
||||
|
||||
@ -43,9 +43,8 @@ In addition, the [binary cache](../integrations/cachix.md) is added for faster d
|
||||
> you can try with sudo: `sudo nix-shell -p cachix --run "cachix use nrdxp"`
|
||||
|
||||
## Next Steps:
|
||||
|
||||
- [Make installable ISO](./iso.md)
|
||||
- [Bootstrap Host](./bootstrapping.md)
|
||||
- [Already on NixOS](./from-nixos.md)
|
||||
|
||||
|
||||
[install-nix]: https://nixos.org/manual/nix/stable/#sect-multi-user-installation
|
||||
|
||||
@ -1,22 +1,36 @@
|
||||
# ISO
|
||||
# Installation Media
|
||||
|
||||
This project leverages [nix-community/nixos-generators][nixos-generators] for
|
||||
building machine images. In most cases, you'll probably want to use the
|
||||
`install-iso` format.
|
||||
|
||||
Making an installable ISO for `hosts/bootstrap.nix` is as simple as:
|
||||
|
||||
Making and writing an installable iso for `hosts/bootstrap.nix` is as simple as:
|
||||
```sh
|
||||
bud build bootstrap bootstrapIso
|
||||
sudo -E $(which bud) burn
|
||||
nix run github:nix-community/nixos-generators -- \
|
||||
--format install-iso \
|
||||
--flake '.#bootstrap'
|
||||
```
|
||||
|
||||
This works for any host.
|
||||
Then "burn" the ISO to your USB stick (or CD-R if you like!) following the
|
||||
[instructions in the NixOS manual][burn] (or using your preferred USB burner).
|
||||
|
||||
## ISO image nix store & cache
|
||||
You can also swap out the `--format` for [any of the others][formats] supported
|
||||
by nixos-generators.
|
||||
|
||||
The iso image holds the store to the live environment and _also_ acts as a binary cache
|
||||
to the installer. To considerably speed up things, the image already includes all flake
|
||||
`inputs` as well as the `devshell` closures.
|
||||
Continue by following the usual installation instructions in the NixOS manual.
|
||||
|
||||
While you _could_ provision any machine with a single stick, a custom-made iso for
|
||||
the host you want to install DevOS to, maximises those local cache hits.
|
||||
## ISO Nix Store and Cache
|
||||
|
||||
For hosts that don't differ too much, a single usb stick might be ok, whereas when
|
||||
there are bigger differences, a custom-made usb stick will be considerably faster.
|
||||
The ISO image holds the Nix store for the live environment and _also_ acts as a
|
||||
binary cache to the installer. To considerably speed things up, the image
|
||||
already includes all flake `inputs` as well as the `devshell` closures.
|
||||
|
||||
While you _could_ provision any NixOS machine with the same USB stick, an ISO
|
||||
custom-made for your target host will maximise those local cache hits. For hosts
|
||||
that don't differ too much, a single USB stick might be ok, whereas when there
|
||||
are bigger differences, a custom-made USB stick will be considerably faster.
|
||||
|
||||
[nixos-generators]: https://github.com/nix-community/nixos-generators
|
||||
[burn]: https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb
|
||||
[formats]: https://github.com/nix-community/nixos-generators/tree/master/formats
|
||||
|
||||
5
examples/devos/.gitignore
vendored
5
examples/devos/.gitignore
vendored
@ -2,9 +2,4 @@ result
|
||||
.direnv
|
||||
doc/index.html
|
||||
|
||||
# Result of bud commands
|
||||
vm
|
||||
iso
|
||||
doi
|
||||
|
||||
pkgs/_sources/.shake*
|
||||
|
||||
@ -24,10 +24,6 @@
|
||||
digga.inputs.home-manager.follows = "home";
|
||||
digga.inputs.deploy.follows = "deploy";
|
||||
|
||||
bud.url = "github:divnix/bud";
|
||||
bud.inputs.nixpkgs.follows = "nixos";
|
||||
bud.inputs.devshell.follows = "digga/devshell";
|
||||
|
||||
home.url = "github:nix-community/home-manager/release-22.05";
|
||||
home.inputs.nixpkgs.follows = "nixos";
|
||||
|
||||
@ -54,7 +50,6 @@
|
||||
outputs =
|
||||
{ self
|
||||
, digga
|
||||
, bud
|
||||
, nixos
|
||||
, home
|
||||
, nixos-hardware
|
||||
@ -111,7 +106,6 @@
|
||||
digga.nixosModules.nixConfig
|
||||
home.nixosModules.home-manager
|
||||
agenix.nixosModules.age
|
||||
bud.nixosModules.bud
|
||||
];
|
||||
};
|
||||
|
||||
|
||||
@ -1,9 +1,5 @@
|
||||
{ profiles, ... }:
|
||||
{
|
||||
# build with: `bud build bootstrap bootstrapIso`
|
||||
# reachable on the local link via ssh root@fe80::47%eno1
|
||||
# where 'eno1' is replaced by your own machine's network
|
||||
# interface that has the local link to the target machine
|
||||
imports = [
|
||||
# profiles.networking
|
||||
profiles.core.nixos
|
||||
@ -13,6 +9,6 @@
|
||||
|
||||
boot.loader.systemd-boot.enable = true;
|
||||
|
||||
# will be overridden by the bootstrapIso instrumentation
|
||||
# Required, but will be overridden in the resulting installer ISO.
|
||||
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
|
||||
}
|
||||
|
||||
@ -1,8 +1,6 @@
|
||||
{ self, inputs, ... }:
|
||||
{
|
||||
modules = with inputs; [
|
||||
bud.devshellModules.bud
|
||||
];
|
||||
modules = with inputs; [];
|
||||
exportedModules = [
|
||||
./devos.nix
|
||||
];
|
||||
|
||||
Loading…
Reference in New Issue
Block a user