bad/devos
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Wiki Activity

Remove doc

Browse source
This commit is contained in:
Bad 2021-08-16 21:49:53 +02:00
parent 7d6e0b4ea5
commit a87e74705b
28 changed files with 0 additions and 1048 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/.gitignore vendored
View file

@ -1 +0,0 @@
book

18
doc/CONTRIBUTING.md
View file

@ -1,18 +0,0 @@
# Pull Requests
## TL;DR;
- **Target Branch**: `main`
- **Merge Policy**: [`bors`][bors] is alwyas right (→ `bors try`)
- **Docs**: every changeset is expected to contain doc updates
- **Commit Msg**: be a poet! Comprehensive and explanatory commit messages
should cover the motivation and use case in an easily understandable manner
even when read after a few months.
- **Test Driven Development**: please default to test driven development where possible.
### Within the Devshell (`nix develop`)
- **Hooks**: please `git commit` within the devshell
- **Fail Early**: please run from within the devshell on your local machine:
- `nix flake check`
[bors]: https://bors.tech

28
doc/SUMMARY.md
View file

@ -1,28 +0,0 @@
# Summary
- [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)
- [Profiles](./concepts/profiles.md)
- [Suites](./concepts/suites.md)
- [Users](./concepts/users.md)
- [Outputs](./outputs/index.md)
- [Modules](./outputs/modules.md)
- [Overlays](./outputs/overlays.md)
- [Packages](./outputs/pkgs.md)
- [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)
- [NvFetcher](./integrations/nvfetcher.md)
- [Hercules CI](./integrations/hercules.md)
- [Contributing](./CONTRIBUTING.md)

6
doc/book.toml
View file

@ -1,6 +0,0 @@
[book]
authors = ["Timothy DeHerrera"]
language = "en"
multilingual = false
src = "."
title = "devos docs"

10
doc/bud/get.md
View file

@ -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_.

24
doc/bud/index.md
View file

@ -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

62
doc/concepts/hosts.md
View file

@ -1,62 +0,0 @@
# Hosts
Nix flakes contain an output called `nixosConfigurations` declaring an
attribute set of valid NixOS systems. To simplify the management and creation
of these hosts, devos automatically imports every _.nix_ file inside this
directory to the mentioned attribute set, applying the projects defaults to
each. The only hard requirement is that the file contain a valid NixOS module.
As an example, a file `hosts/system.nix` or `hosts/system/default.nix` will
be available via the flake output `nixosConfigurations.system`. You can have
as many hosts as you want and all of them will be automatically imported based
on their name.
For each host, the configuration automatically sets the `networking.hostName`
attribute to the folder name or name of the file minus the _.nix_ extension. This
is for convenience, since `nixos-rebuild` automatically searches for a configuration
matching the current systems hostname if one is not specified explicitly.
You can set channels, systems, and add extra modules to each host by editing the
`nixos.hosts` argument in flake.nix. This is the perfect place to import
host specific modules from external sources, such as the
[nixos-hardware][nixos-hardware] repository.
It is recommended that the host modules only contain configuration information
specific to a particular piece of hardware. Anything reusable across machines
is best saved for [profile modules](./profiles.md).
This is a good place to import sets of profiles, called [suites](./suites.md),
that you intend to use on your machine.
## Example
flake.nix:
```nix
{
nixos = {
imports = [ (devos.lib.importHosts ./hosts) ];
hosts = {
librem = {
channelName = "latest";
modules = [ nixos-hardware.nixosModules.purism-librem-13v3 ];
};
};
};
}
```
hosts/librem.nix:
```nix
{ suites, ... }:
{
imports = suites.laptop;
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
}
```
[nixos-hardware]: https://github.com/NixOS/nixos-hardware

10
doc/concepts/index.md
View file

@ -1,10 +0,0 @@
# Key Concepts
Key concepts are derived from [digga][digga]. Please refer to its
[docs][digga-docs] for more details.
This section is dedicated to helping you develop a more hands on
understanding of them them.
[digga-docs]: https://digga.divnix.com
[digga]: https://github.com/divnix/digga

42
doc/concepts/overrides.md
View file

@ -1,42 +0,0 @@
# Overrides
Each NixOS host follows one channel. But many times it is useful to get packages
or modules from different channels.
## Packages
You can make use of `overlays/overrides.nix` to override specific packages in the
default channel to be pulled from other channels. That file is simply an example
of how any overlay can get `channels` as their first argument.
You can add overlays to any channel to override packages from other channels.
Pulling the manix package from the `latest` channel:
```nix
channels: final: prev: {
__dontExport = true;
inherit (pkgs.latest) manix;
}
```
It is recommended to set the `__dontExport` property for override specific
overlays. `overlays/overrides.nix` is the best place to consolidate all package
overrides and the property is already set for you.
## Modules
You can also pull modules from other channels. All modules have access to the
`modulesPath` for each channel as `<channelName>ModulesPath`. And you can use
`disabledModules` to remove modules from the current channel.
To pull zsh module from the `latest` channel this code can be placed in any module, whether its your host file, a profile, or a module in ./modules etc:
```nix
{ latestModulesPath }:
{
imports = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
disabledModules = [ "programs/zsh/zsh.nix" ];
}
```
> ##### _Note:_
> Sometimes a modules name will change from one branch to another.
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

67
doc/concepts/profiles.md
View file

@ -1,67 +0,0 @@
# Profiles
Profiles are a convenient shorthand for the [_definition_][definition] of
[options][options] in contrast to their [_declaration_][declaration]. They're
built into the NixOS module system for a reason: to elegantly provide a clear
separation of concerns.
## Creation
Profiles are created with the `rakeLeaves` function which recursively collects
`.nix` files from within a folder. The recursion stops at folders with a `default.nix`
in them. You end up with an attribute set with leaves(paths to profiles) or
nodes(attrsets leading to more nodes or leaves).
A profile is used for quick modularization of [interelated bits](./profiles.md#subprofiles).
> ##### _Notes:_
> * For _declaring_ module options, there's the [modules](../outputs/modules.md) directory.
> * This directory takes inspiration from
> [upstream](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/profiles)
> .
### Nested profiles
Profiles can be nested in attribute sets due to the recursive nature of `rakeLeaves`.
This can be useful to have a set of profiles created for a specific purpose. It is
sometimes useful to have a `common` profile that has high level concerns related
to all its sister profiles.
### Example
profiles/develop/common.nix:
```nix
{
imports = [ ./zsh ];
# some generic development concerns ...
}
```
profiles/develop/zsh.nix:
```nix
{ ... }:
{
programs.zsh.enable = true;
# zsh specific options ...
}
```
The examples above will end up with a profiles set like this:
```nix
{
develop = {
common = ./profiles/develop/common.nix;
zsh = ./profiles/develop/zsh.nix;
};
}
```
## Conclusion
Profiles are the most important concept in DevOS. They allow us to keep our
Nix expressions self contained and modular. This way we can maximize reuse
across hosts while minimizing boilerplate. Remember, anything machine
specific belongs in your [host](hosts.md) files instead.
[definition]: https://nixos.org/manual/nixos/stable/index.html#sec-option-definitions
[declaration]: https://nixos.org/manual/nixos/stable/index.html#sec-option-declarations
[options]: https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules
[spec]: https://github.com/divnix/devos/tree/core/lib/devos/mkProfileAttrs.nix
[config]: https://nixos.wiki/wiki/Module#structure

25
doc/concepts/suites.md
View file

@ -1,25 +0,0 @@
# Suites
Suites provide a mechanism for users to easily combine and name collecitons of
profiles.
`suites` are defined in the `importables` argument in either the `home` or `nixos`
namespace. They are a special case of an `importable` which get passed as a special
argument (one that can be use in an `imports` line) to your hosts. All lists defined
in `suites` are flattened and type-checked as paths.
## Definition
```nix
rec {
workstation = [ profiles.develop profiles.graphical users.nixos ];
mobileWS = workstation ++ [ profiles.laptop ];
}
```
## Usage
`hosts/my-laptop.nix`:
```nix
{ suites, ... }:
{
imports = suites.mobileWS;
}
```

77
doc/concepts/users.md
View file

@ -1,77 +0,0 @@
> ##### _Note:_
> This section and its semantics need a conceptiual rework.
> Since recently [portable home configurations][portableuser]
> that are not bound to any specific host are a thing.
# Users
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).
## Basic Usage
`users/myuser/default.nix`:
```nix
{ ... }:
{
users.users.myuser = {
isNormalUser = true;
};
home-manager.users.myuser = {
programs.mpv.enable = true;
};
}
```
## Home Manager
Home Manager support follows the same principles as regular nixos configurations,
it even gets its own namespace in your `flake.nix` as `home`.
All modules defined in [user modules][modules-list] will be imported to
Home Manager.
User profiles can be collected in a similar fashion as system ones into a `suites`
argument that gets passed to your home-manager users.
### Example
```nix
{
home-manager.users.nixos = { suites, ... }: {
imports = suites.base;
};
}
```
## External Usage
You can easily use the defined home-manager configurations outside of NixOS
using the `homeConfigurations` flake output. The [flk](../flk/index.md) helper
script makes this even easier.
This is great for keeping your environment consistent across Unix systems,
including OSX.
### From within the projects devshell:
```sh
# builds the nixos user defined in the NixOS host
flk home NixOS nixos
# build and activate
flk home NixOS nixos switch
```
### Manually from outside the project:
```sh
# build
nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPackage"
# activate
./result/activate && unlink result
```
[home-manager]: https://nix-community.github.io/home-manager
[modules-list]: https://github.com/divnix/devos/tree/core/users/modules/module-list.nix
[portableuser]: https://digga.divnix.com/api-reference-home.html#homeusers

17
doc/integrations/cachix.md
View file

@ -1,17 +0,0 @@
# Cachix
The system will automatically pull a cachix.nix at the root if one exists.
This is usually created automatically by a `sudo cachix use`. If you're more
inclined to keep the root clean, you can drop any generated files in the
`cachix` directory into the `profiles/cachix` directory without further
modification.
For example, to add your own cache, assuming the template lives in /etc/nixos,
by simply running `sudo cachix use yourcache`. Then, optionally, move
`cachix/yourcache.nix` to `profiles/cachix/yourcache.nix`
These caches are only added to the system after a `nixos-rebuild switch`, so it
is recommended to call `cachix use nrdxp` before the initial deployment, as it
will save a lot of build time.
In the future, users will be able to skip this step once the ability to define
the nix.conf within the flake is fully fleshed out upstream.

49
doc/integrations/deploy.md
View file

@ -1,49 +0,0 @@
# deploy-rs
[Deploy-rs][d-rs] is a tool for managing NixOS remote machines. It was
chosen for devos after the author experienced some frustrations with the
stateful nature of nixops' db. It was also designed from scratch to support
flake based deployments, and so is an excellent tool for the job.
By default, all the [hosts](../concepts/hosts.md) are also available as deploy-rs nodes,
configured with the hostname set to `networking.hostName`; overridable via
the command line.
## Usage
Just add your ssh key to the host:
```nix
{ ... }:
{
users.users.${sshUser}.openssh.authorizedKeys.keyFiles = [
../secrets/path/to/key.pub
];
}
```
And the private key to your user:
```nix
{ ... }:
{
home-manager.users.${sshUser}.programs.ssh = {
enable = true;
matchBlocks = {
${host} = {
host = hostName;
identityFile = ../secrets/path/to/key;
extraOptions = { AddKeysToAgent = "yes"; };
};
};
}
}
```
And run the deployment:
```sh
deploy "flk#hostName" --hostname host.example.com
```
> ##### _Note:_
> Your user will need **passwordless** sudo access
[d-rs]: https://github.com/serokell/deploy-rs

36
doc/integrations/hercules.md
View file

@ -1,36 +0,0 @@
# Hercules CI
If you start adding your own packages and configurations, you'll probably have
at least a few binary artifacts. With hercules we can build every package in
our configuration automatically, on every commit. Additionally, we can have it
upload all our build artifacts to a binary cache like [cachix][cachix].
This will work whether your copy is a fork, or a bare template, as long as your
repo is hosted on GitHub.
## Setup
Just head over to [hercules-ci.com](https://hercules-ci.com) to make an account.
Then follow the docs to set up an [agent][agent], if you want to deploy to a
binary cache (and of course you do), be sure _not_ to skip the
[binary-caches.json][cache].
## Ready to Use
The repo is already set up with the proper _default.nix_ file, building all
declared packages, checks, profiles and shells. So you can see if something
breaks, and never build the same package twice!
If you want to get fancy, you could even have hercules
[deploy your configuration](https://docs.hercules-ci.com/hercules-ci-effects/guide/deploy-a-nixos-machine/)!
> ##### _Note:_
> Hercules doesn't have access to anything encrypted in the
> [secrets folder](../../secrets), so none of your secrets will accidentally get
> pushed to a cache by mistake.
>
> You could pull all your secrets via your user, and then exclude it from
> [allUsers](https://github.com/nrdxp/devos/blob/nrd/suites/default.nix#L17)
> to keep checks passing.
[agent]: https://docs.hercules-ci.com/hercules-ci/getting-started/#github
[cache]: https://docs.hercules-ci.com/hercules-ci/getting-started/deploy/nixos/#_3_configure_a_binary_cache
[cachix]: https://cachix.org

5
doc/integrations/index.md
View file

@ -1,5 +0,0 @@
# Integrations
This section explores some of the optional tools included with devos to provide
a solution to common concerns such as ci and remote deployment. An effort is
made to choose tools that treat nix, and where possible flakes, as first class
citizens.

43
doc/integrations/nvfetcher.md
View file

@ -1,43 +0,0 @@
# nvfetcher
[NvFetcher][nvf] is a workflow companion for updating nix sources.
You can specify an origin source and an update configuration, and
nvfetcher can for example track updates to a specific branch and
automatically update your nix sources configuration on each run
to the tip of that branch.
All package source declaration is done in [sources.toml][sources.toml].
From within the devshell of this repo, run `nvfetcher`, a wrapped
version of `nvfetcher` that knows where to find and place its files
and commit the results.
## Usage
Statically fetching (not tracking) a particular tag from a github repo:
```toml
[manix]
src.manual = "v0.6.3"
fetch.github = "mlvzk/manix"
```
Tracking the latest github _release_ from a github repo:
```toml
[manix]
src.github = "mlvzk/manix" # responsible for tracking
fetch.github = "mlvzk/manix" # responsible for fetching
```
Tracking the latest commit of a git repository and fetch from a git repo:
```toml
[manix]
src.git = "https://github.com/mlvzk/manix.git" # responsible for tracking
fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
```
> ##### _Note:_
> Please refer to the [NvFetcher Readme][nvf-readme] for more options.
[nvf]: https://github.com/berberman/nvfetcher
[nvf-readme]: https://github.com/berberman/nvfetcher#readme
[sources.toml]: https://github.com/divnix/devos/tree/core/pkgs/sources.toml

3
doc/outputs/index.md
View file

@ -1,3 +0,0 @@
# Layout
Each of the following sections is a directory whose contents are output to the
outside world via the flake's outputs. Check each chapter for details.

79
doc/outputs/modules.md
View file

@ -1,79 +0,0 @@
# Modules
The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-modules]
, and follows the same semantics. This allows for trivial upstreaming into
nixpkgs proper once your module is sufficiently stable.
All modules linked in _module-list.nix_ are automatically exported via
`nixosModules.<file-basename>`, and imported into all [hosts](../concepts/hosts.md).
> ##### _Note:_
> This is reserved for declaring brand new module options. If you just want to
> declare a coherent configuration of already existing and related NixOS options
> , use [profiles](../concepts/profiles.md) instead.
## Semantics
In case you've never written a module for nixpkgs before, here is a brief
outline of the process.
### Declaration
modules/services/service-category/my-service.nix:
```nix
{ config, lib, ... }:
let
cfg = config.services.myService;
in
{
options.services.myService = {
enable = lib.mkEnableOption "Description of my new service.";
# additional options ...
};
config = lib.mkIf cfg.enable {
# implementation ...
};
}
```
### Import
modules/module-list.nix:
```nix
[
./services/service-category/my-service.nix
]
```
## Usage
### Internal
profiles/profile-category/my-profile.nix:
```nix
{ ... }:
{
services.MyService.enable = true;
}
```
### External
flake.nix:
```nix
{
# inputs omitted
outputs = { self, devos, nixpkgs, ... }: {
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "...";
modules = [
devos.nixosModules.my-service
({ ... }: {
services.MyService.enable = true;
})
];
};
};
}
```
[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules

25
doc/outputs/overlays.md
View file

@ -1,25 +0,0 @@
# Overlays
Writing overlays is a common occurence when using a NixOS system. Therefore,
we want to keep the process as simple and straightforward as possible.
Any _.nix_ files declared in this directory will be assumed to be a valid
overlay, and will be automatically imported into all [hosts](../concepts/hosts.md), and
exported via `overlays.<channel>/<pkgName>` _as well as_
`packages.<system>.<pkgName>` (for valid systems), so all you have to do is
write it.
## Example
overlays/kakoune.nix:
```nix
final: prev: {
kakoune = prev.kakoune.override {
configure.plugins = with final.kakounePlugins; [
(kak-fzf.override { fzf = final.skim; })
kak-auto-pairs
kak-buffers
kak-powerline
kak-vertical-selection
];
};
}
```

54
doc/outputs/pkgs.md
View file

@ -1,54 +0,0 @@
# Packages
Similar to [modules](./modules.md), the pkgs directory mirrors the upstream
[nixpkgs/pkgs][pkgs], and for the same reason; if you ever want to upstream
your package, it's as simple as dropping it into the nixpkgs/pkgs directory.
The only minor difference is that, instead of adding the `callPackage` call to
`all-packages.nix`, you just add it the the _default.nix_ in this directory,
which is defined as a simple overlay.
All the packages are exported via `packages.<system>.<pkg-name>`, for all
the supported systems listed in the package's `meta.platforms` attribute.
And, as usual, every package in the overlay is also available to any NixOS
[host](../concepts/hosts.md).
## Example
pkgs/development/libraries/libinih/default.nix:
```nix
{ stdenv, meson, ninja, lib, srcs, ... }:
let inherit (srcs) libinih; in
stdenv.mkDerivation {
pname = "libinih";
# version will resolve to 53, as specified in the final example below
inherit (libinih) version;
src = libinih;
buildInputs = [ meson ninja ];
# ...
}
```
pkgs/default.nix:
```nix
final: prev: {
libinih = prev.callPackage ./development/libraries/libinih { };
}
```
pkgs/flake.nix:
```nix
{
description = "Package sources";
inputs = {
libinih.url = "github:benhoyt/inih/r53";
libinih.flake = false;
};
}
```
[pkgs]: https://github.com/NixOS/nixpkgs/tree/master/pkgs

110
doc/secrets.md
View file

@ -1,110 +0,0 @@
# Secrets
Secrets are managed using [git-crypt][git-crypt] and [agenix][agenix]
so you can keep your flake in a public repository like GitHub without
exposing your password or other sensitive data.
By default, everything in the secrets folder is automatically encrypted. Just
be sure to run `git-crypt init` before putting anything in here.
## Agenix
Currently, there is [no mechanism][secrets-issue] in nix itself to deploy secrets
within the nix store because it is world-readable.
Most NixOS modules have the ability to set options to files in the system, outside
the nix store, that contain sensitive information. You can use [agenix][agenix]
to easily setup those secret files declaratively.
[agenix][agenix] encrypts secrets and stores them as .age files in your repository.
Age files are encrypted with multiple ssh public keys, so any host or user with a
matching ssh private key can read the data. The [age module][age module] will add those
encrypted files to the nix store and decrypt them on activation to `/run/secrets`.
### Setup
All hosts must have openssh enabled, this is done by default in the core profile.
You need to populate your `secrets/secrets.nix` with the proper ssh public keys.
Be extra careful to make sure you only add public keys, you should never share a
private key!!
secrets/secrets.nix:
```nix
let
system = "<system ssh key>";
user = "<user ssh key>";
allKeys = [ system user ];
in
```
On most systems, you can get your systems ssh public key from `/etc/ssh/ssh_host_ed25519_key.pub`. If
this file doesn't exist you likely need to enable openssh and rebuild your system.
Your users ssh public key is probably stored in `~/.ssh/id_ed25519.pub` or
`~/.ssh/id_rsa.pub`. If you haven't generated a ssh key yet, be sure do so:
```sh
ssh-keygen -t ed25519
```
> ##### _Note:_
> The underlying tool used by agenix, rage, doesn't work well with password protected
> ssh keys. So if you have lots of secrets you might have to type in your password many
> times.
### Secrets
You will need the `agenix` command to create secrets. DevOS conveniently provides that
in the devShell, so just run `nix develop` whenever you want to edit secrets. Make sure
to always run `agenix` while in the `secrets/` folder, so it can pick up your `secrets.nix`.
To create secrets, simply add lines to your `secrets/secrets.nix`:
```
let
...
allKeys = [ system user ];
in
{
"secret.age".publicKeys = allKeys;
}
```
That would tell agenix to create a `secret.age` file that is encrypted with the `system`
and `user` ssh public key.
Then go into the `secrets` folder and run:
```sh
agenix -e secret.age
```
This will create the `secret.age`, if it doesn't already exist, and allow you to edit it.
If you ever change the `publicKeys` entry of any secret make sure to rekey the secrets:
```sh
agenix --rekey
```
### Usage
Once you have your secret file encrypted and ready to use, you can utilize the [age module][age module]
to ensure that your secrets end up in `/run/secrets`.
In any profile that uses a NixOS module that requires a secret you can enable a particular secret like so:
```nix
{ self, ... }:
{
age.secrets.mysecret.file = "${self}/secrets/mysecret.age";
}
```
Then you can just pass the path `/run/secrets/mysecret` to the module.
You can make use of the many options provided by the age module to customize where and how
secrets get decrypted. You can learn about them by looking at the
[age module][age module].
> ##### _Note:_
> You can take a look at the [agenix repository][agenix] for more information
> about the tool.
[git-crypt]: https://github.com/AGWA/git-crypt
[agenix]: https://github.com/ryantm/agenix
[age module]: https://github.com/ryantm/agenix/blob/master/modules/age.nix
[secrets-issue]: https://github.com/NixOS/nix/issues/8

99
doc/start/bootstrapping.md
View file

@ -1,99 +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 partion
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 &mdash; for UEFI &mdash; `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/$your_swap_partition
```
## Install
Install using the `flk` wrapper baked into the iso off of a copy of devos
from the time the iso was built:
```console
$ cd /iso/devos
$ nix develop
$ flk install NixOS --impure # use same host as above
```
<!-- TODO: find out why --impure is necesary / PRs welcome! -->
## 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 `NixOS.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@NixOS.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

54
doc/start/from-nixos.md
View file

@ -1,54 +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
flk up
```
This will make a new file `hosts/up-$(hostname).nix`, which you can edit to
your liking.
You must then add a host to `nixos.hosts` in flake.nix:
```nix
{
nixos.hosts = {
modules = hosts/NixOS.nix;
};
}
```
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/my-host.nix`:
```sh
flk my-host 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`.
>
> - It is convenient to have the template living at `/etc/nixos` so you can
> simply `sudo nixos-rebuild switch` from anywhere on the system, but it is
> not required.

41
doc/start/index.md
View file

@ -1,41 +0,0 @@
# Quick Start
The only dependency is nix, so make sure you have it [installed][install-nix].
## Get the Template
Here is a snippet that will get you the template without the git history:
```sh
nix-shell -p cachix --run "cachix use nrdxp"
nix-shell https://github.com/divnix/devos/archive/core.tar.gz -A shell \
--run "flk get core"
cd flk
nix-shell
git init
git add .
git commit -m init
```
This will place you in a new folder named `flk` with git initialized, and a
nix-shell that provides all the dependencies, including the unstable nix
version required.
In addition, the [binary cache](../integrations/cachix.md) is added for faster deployment.
> ##### _Notes:_
> - Flakes ignore files that have not been added to git, so be sure to stage new
> files before building the system.
> - You can choose to simply clone the repo with git if you want to follow
> upstream changes.
> - If the `nix-shell -p cachix --run "cachix use nrdxp"` line doesn't work
> 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

24
doc/start/iso.md
View file

@ -1,24 +0,0 @@
# ISO
Making and writing an installable iso for `hosts/NixOS.nix` is as simple as:
```sh
bud build NixOS bootstrapIso
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
status=progress oflag=sync
```
This works for any host.
## ISO image nix store & cache
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.
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.
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.

33
doc/tests.md
View file

@ -1,33 +0,0 @@
# Testing
Testing is always an important aspect of any software development project, and
NixOS offers some incredibly powerful tools to write tests for your
configuration, and, optionally, run them in
[CI](./integrations/hercules.md).
## Unit Tests
Unit tests can be created from regular derivations, and they can do
almost anything you can imagine. By convention, it is best to test your
packages during their [check phase][check]. All packages and their tests will
be built during CI.
## Integration Tests
All your profiles defined in suites will be tested in a NixOS VM.
You can write integration tests for one or more NixOS VMs that can,
optionally, be networked together, and yes, it's as awesome as it sounds!
Be sure to use the `mkTest` function from digga, `digga.lib.pkgs-lib.mkTest`
which wraps the official [testing-python][testing-python] function to ensure
that the system is setup exactly as it is for a bare DevOS system. There are
already great resources for learning how to use these tests effectively,
including the official [docs][test-doc], a fantastic [blog post][test-blog],
and the examples in [nixpkgs][nixos-tests].
[test-doc]: https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests
[test-blog]: https://www.haskellforall.com/2020/11/how-to-use-nixos-for-lightweight.html
[default]: https://github.com/divnix/devos/tree/core/tests/default.nix
[run-test]: https://github.com/NixOS/nixpkgs/blob/6571462647d7316aff8b8597ecdf5922547bf365/lib/debug.nix#L154-L166
[nixos-tests]: https://github.com/NixOS/nixpkgs/tree/master/nixos/tests
[testing-python]: https://github.com/NixOS/nixpkgs/tree/master/nixos/lib/testing-python.nix
[check]: https://nixos.org/manual/nixpkgs/stable/#ssec-check-phase

6
doc/theme/highlight.js vendored
View file

File diff suppressed because one or more lines are too long