holy moly we're almost there
This commit is contained in:
Anish Lakhwara
@@ -0,0 +1,62 @@
|
||||
# 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
|
||||
@@ -0,0 +1,10 @@
|
||||
# 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
|
||||
@@ -0,0 +1,42 @@
|
||||
# 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
|
||||
@@ -0,0 +1,67 @@
|
||||
# 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
|
||||
@@ -0,0 +1,25 @@
|
||||
# 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;
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
> ##### _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
|
||||
Reference in New Issue
Block a user