doc: move all docs under `doc`
Timothy DeHerrera
parent
048171ecaf
commit
2d91946745
|
|
@ -2,4 +2,4 @@ result
|
|||
up
|
||||
hosts/up-*
|
||||
.direnv
|
||||
book
|
||||
doc/index.html
|
||||
|
|
|
|||
|
|
@ -55,10 +55,10 @@ There are two branches from which to choose: [core][core] and
|
|||
several ready-made profiles for discretionary use.
|
||||
|
||||
Every package and NixOS profile declared in community is uploaded to
|
||||
[cachix](./cachix), so everything provided is available without building
|
||||
anything. This is especially useful for the packages that are
|
||||
[overridden](./overrides) from master, as without the cache, rebuilds are
|
||||
quite frequent.
|
||||
[cachix](./integrations/cachix.md), so everything provided is available
|
||||
without building anything. This is especially useful for the packages that are
|
||||
[overridden](./concepts/overrides.md) from master, as without the cache,
|
||||
rebuilds are quite frequent.
|
||||
|
||||
## Inspiration & Art
|
||||
- [hlissner/dotfiles][dotfiles]
|
||||
|
|
|
|||
32
SUMMARY.md
32
SUMMARY.md
|
|
@ -1,32 +0,0 @@
|
|||
# Summary
|
||||
|
||||
- [Introduction](./README.md)
|
||||
- [Quick Start](./doc/start/index.md)
|
||||
- [ISO](./doc/start/iso.md)
|
||||
- [Bootstrapping](./doc/start/bootstrapping.md)
|
||||
- [From NixOS](./doc/start/from-nixos.md)
|
||||
- [Layout](./doc/layout.md)
|
||||
- [Cachix](./cachix/README.md)
|
||||
- [Extern](./extern/README.md)
|
||||
- [Hosts](./hosts/README.md)
|
||||
- [Lib](./lib/README.md)
|
||||
- [Modules](./modules/README.md)
|
||||
- [Overlays](./overlays/README.md)
|
||||
- [Overrides](./overrides/README.md)
|
||||
- [Packages](./pkgs/README.md)
|
||||
- [Profiles](./profiles/README.md)
|
||||
- [Secrets](./secrets/README.md)
|
||||
- [Suites](./suites/README.md)
|
||||
- [Tests](./tests/README.md)
|
||||
- [Users](./users/README.md)
|
||||
- [flk](./doc/flk/index.md)
|
||||
- [up](./doc/flk/up.md)
|
||||
- [update](./doc/flk/update.md)
|
||||
- [get](./doc/flk/get.md)
|
||||
- [iso](./doc/flk/iso.md)
|
||||
- [install](./doc/flk/install.md)
|
||||
- [home](./doc/flk/home.md)
|
||||
- [Integrations](doc/integrations/index.md)
|
||||
- [Deploy RS](./doc/integrations/deploy.md)
|
||||
- [Hercules CI](./doc/integrations/hercules.md)
|
||||
- [Contributing](./doc/README.md)
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
# 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)
|
||||
- [Extern](./concepts/extern.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]()
|
||||
- [Lib](./lib.md)
|
||||
- [Secrets](./secrets.md)
|
||||
- [Tests](./tests.md)
|
||||
- [Helper Script – `flk`](./flk/index.md)
|
||||
- [up](./flk/up.md)
|
||||
- [update](./flk/update.md)
|
||||
- [get](./flk/get.md)
|
||||
- [iso](./flk/iso.md)
|
||||
- [install](./flk/install.md)
|
||||
- [home](./flk/home.md)
|
||||
- [Integrations](./integrations/index.md)
|
||||
- [Cachix](./integrations/cachix.md)
|
||||
- [Deploy RS](./integrations/deploy.md)
|
||||
- [Hercules CI](./integrations/hercules.md)
|
||||
- [Contributing](./CONTRIBUTING.md)
|
||||
|
|
@ -17,16 +17,16 @@ matching the current systems hostname if one is not specified explicitly.
|
|||
|
||||
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).
|
||||
is best saved for [profile modules](./profiles.md).
|
||||
|
||||
This is a good place to import sets of profiles, called [suites](../suites),
|
||||
This is a good place to import sets of profiles, called [suites](./suites.md),
|
||||
that you intend to use on your machine.
|
||||
|
||||
Additionally, this is the perfect place to import anything you might need from
|
||||
the [nixos-hardware][nixos-hardware] repository.
|
||||
|
||||
> ##### _Note:_
|
||||
> Set `nixpkgs.system` to the architecture of this host, default is "x86_64-linux".
|
||||
> Set `nixpkgs.system` to the architecture of this host, default is "x86_64-linux".
|
||||
> Keep in mind that not all packages are available for all architectures.
|
||||
|
||||
## Example
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
# Key Concepts
|
||||
|
||||
There are few idioms unique to DevOS. This section is dedicated to helping you
|
||||
understand them.
|
||||
|
|
@ -12,17 +12,17 @@ is maintained to help get up to speed on their usage.
|
|||
For the sake of consistency, a profile should always be defined in a
|
||||
___default.nix___ containing a [nixos module config][config].
|
||||
A profile's directory is used for quick modularization of
|
||||
[interelated bits](./#subprofiles).
|
||||
[interelated bits](./profiles.md#subprofiles).
|
||||
|
||||
> ##### _Notes:_
|
||||
> * For _declaring_ module options, there's the [modules](../modules) directory.
|
||||
> * 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)
|
||||
> .
|
||||
> * Sticking to a simple [spec][spec] has refreshing advantages.
|
||||
> [hercules-ci](../doc/integrations/hercules.md) expects all profiles to be
|
||||
> [hercules-ci](../integrations/hercules.md) expects all profiles to be
|
||||
> defined in a ___default.nix___, allowing them to be built automatically when
|
||||
> added. Congruently, [suites](../suites) expect ___default.nix___ to avoid
|
||||
> added. Congruently, [suites](suites.md) expect ___default.nix___ to avoid
|
||||
> having to manage their paths manually.
|
||||
|
||||
## Subprofiles
|
||||
|
|
@ -56,7 +56,7 @@ profiles/develop/zsh/default.nix:
|
|||
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) files instead.
|
||||
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
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Users
|
||||
|
||||
Users are a special case of [profiles](../profiles) that define system
|
||||
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
|
||||
|
|
@ -24,14 +24,14 @@ your users. For a fully fleshed out example, check out the developers personal
|
|||
|
||||
## Home Manager
|
||||
Home Manager support follows the same principles as regular nixos configurations.
|
||||
All modules defined in [user modules](./modules/module-list.nix) will be imported to
|
||||
Home Manager. All profiles are availabe in [suites](../suites/default.nix) as userProfiles.
|
||||
All modules defined in [user modules][modules-list] will be imported to
|
||||
Home Manager. All profiles are availabe in [suites][suites] as userProfiles.
|
||||
The `userSuites` output will be available in your Home Manager Configuration as
|
||||
the special argument, `suites`.
|
||||
|
||||
## External Usage
|
||||
You can easily use the defined home-manager configurations outside of NixOS
|
||||
using the `homeConfigurations` flake output. The [flk](../doc/flk) helper
|
||||
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,
|
||||
|
|
@ -56,3 +56,5 @@ nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPac
|
|||
```
|
||||
|
||||
[home-manager]: https://nix-community.github.io/home-manager
|
||||
[suites]: https://github.com/divnix/devos/tree/core/suites/default.nix
|
||||
[modules-list]: https://github.com/divnix/devos/tree/core/modules/module-list.nix
|
||||
|
|
@ -4,5 +4,5 @@ NixOS, providing an awesome mechanism for keeping your environments
|
|||
synchronized, even when using other systems.
|
||||
|
||||
## Usage
|
||||
The [users](../../users/index.md#external-usage) page contains a good usage
|
||||
The [users](../concepts/users.md#external-usage) page contains a good usage
|
||||
example.
|
||||
|
|
|
|||
|
|
@ -11,8 +11,8 @@ contains a flake.nix, with an optional arguement to update only a specific
|
|||
input in the subflake.
|
||||
|
||||
For example, you can update any
|
||||
[package sources](../../pkgs#automatic-source-updates) you may have declared
|
||||
in _pkgs/flake.nix_:
|
||||
[package sources](../outputs/pkgs.md#automatic-source-updates) you may have
|
||||
declared in _pkgs/flake.nix_:
|
||||
```sh
|
||||
flk update pkgs
|
||||
```
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ 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](../../hosts) are also available as deploy-rs nodes,
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
# Layout
|
||||
Each of the following sections is a directory in the root of the project
|
||||
serving a singular purpose. Select a chapter to read more about its purpose
|
||||
and usage.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# 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.
|
||||
|
|
@ -4,13 +4,13 @@ The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-modules]
|
|||
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](../hosts).
|
||||
`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](../profiles) instead.
|
||||
> , use [profiles](../concepts/profiles.md) instead.
|
||||
|
||||
## Semantics
|
||||
In case you've never written a module for nixpkgs before, here is a brief
|
||||
|
|
@ -3,7 +3,7 @@ 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](../hosts), and
|
||||
overlay, and will be automatically imported into all [hosts](../concepts/hosts.md), and
|
||||
exported via `overlays.<file-basename>` _as well as_
|
||||
`packages.<system>.<pkgName>` (for valid systems), so all you have to do is
|
||||
write it.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
# Packages
|
||||
Similar to [modules](../modules), the pkgs directory mirrors the upstream
|
||||
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.
|
||||
|
||||
|
|
@ -12,18 +12,17 @@ And 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](../hosts).
|
||||
[host](../concepts/hosts.md).
|
||||
|
||||
## Automatic Source Updates
|
||||
There is the added, but optional, convenience of declaring your sources in
|
||||
_pkgs/flake.nix_ as an input. You can then access them from the `srcs` package.
|
||||
This allows updates to be managed automatically by simply
|
||||
[updating](../doc/flk/update.md#updating-package-sources) the lock file. No
|
||||
[updating](../flk/update.md#updating-package-sources) the lock file. No
|
||||
more manually entering sha256 hashes!
|
||||
|
||||
As an added bonus, version strings are also generated automatically from either
|
||||
the flake ref, or the date and git revision of the source. For examples,
|
||||
definitely checkout the [community branch](../#community-profiles).
|
||||
the flake ref, or the date and git revision of the source.
|
||||
|
||||
## Example
|
||||
pkgs/development/libraries/libinih/default.nix:
|
||||
|
|
@ -1,9 +1,9 @@
|
|||
# Bootstrapping
|
||||
|
||||
This will help you boostrap a bare host with the help of the
|
||||
[bespoke iso](./iso) live installer.
|
||||
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
|
||||
_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
|
||||
|
|
@ -14,7 +14,7 @@ and format your disk according to the [official manual][manual].
|
|||
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`
|
||||
Mount `nixos` partition to `/mnt` and — for UEFI — `boot`
|
||||
partition to `/mnt/boot`:
|
||||
|
||||
```console
|
||||
|
|
@ -25,7 +25,7 @@ $ swapon /dev/$your_swap_partition
|
|||
|
||||
## Install
|
||||
|
||||
Install using the `flk` wrapper baked into the iso off of a copy of devos
|
||||
Install using the `flk` wrapper baked into the iso off of a copy of devos
|
||||
from the time the iso was built:
|
||||
|
||||
```console
|
||||
|
|
@ -41,7 +41,7 @@ $ flk install NixOS --impure # use same host as above
|
|||
### 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`,
|
||||
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
|
||||
|
|
@ -50,7 +50,7 @@ in your network, there is a static link-local IPv6 address configured to
|
|||
`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) needs passwordless
|
||||
`root` user _(hint: [`deploy-rs`](../integrations/deploy.md) needs passwordless
|
||||
sudo access)_:
|
||||
|
||||
```nix
|
||||
|
|
@ -62,7 +62,7 @@ sudo access)_:
|
|||
}
|
||||
```
|
||||
|
||||
You can then ssh into the live installer through one of the
|
||||
You can then ssh into the live installer through one of the
|
||||
following options:
|
||||
|
||||
```console
|
||||
|
|
@ -73,7 +73,7 @@ ssh root@fe80::47%eno1 # where eno1 is your network interface on which you are
|
|||
|
||||
_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](../../profiles)._
|
||||
for your environment, you ought to configure that in a regular [profile](../concepts/profiles.md)._
|
||||
|
||||
### EUI-64 LLA & Host Identity
|
||||
|
||||
|
|
@ -88,7 +88,7 @@ specific address over [NDP][NDP] for example with:
|
|||
ip -6 neigh show # also shows fe80::47
|
||||
```
|
||||
|
||||
***This LLA is stable for the host, unless you need to swap that particular network card.***
|
||||
***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.
|
||||
|
||||
|
|
|
|||
|
|
@ -15,8 +15,8 @@ your region. Keep in mind that `networking.hostName` with be automatically
|
|||
set to the filename of your hosts file, so `hosts/my-host.nix` will have the
|
||||
hostname `my-host`.
|
||||
|
||||
Now might be a good time to read the docs on [suites](../../suites) and
|
||||
[profiles](../../profiles) and add or create any that you need.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ 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](../../cachix) is added for faster deployment.
|
||||
In addition, the [binary cache](../integrations/cachix.md) is added for faster deployment.
|
||||
|
||||
> ##### _Notes:_
|
||||
> - You can change `core` to [`community`](../../index.md#community-profiles)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,36 @@
|
|||
# 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).
|
||||
|
||||
## Lib Tests
|
||||
You can easily write tests for your own library functions in the
|
||||
___tests/lib.nix___ file and they will be run on every `nix flake check` or
|
||||
during a CI run.
|
||||
|
||||
## Unit Tests
|
||||
Unit tests are 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
|
||||
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, in the [___tests/default.nix___][default]
|
||||
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
|
||||
Loading…
Reference in New Issue