foodogsquared/nixos-config
1
0
Fork 0
mirror of https://github.com/foo-dogsquared/nixos-config.git synced 2025-01-31 04:58:01 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs/site: update the book after the flake-parts restructuring

Browse Source
This commit is contained in:
Gabriel Arazas 2024-01-16 20:07:58 +08:00
parent 6ae54e2b55
commit 861b1065cc
No known key found for this signature in database
GPG Key ID: ADE0C41DAB221FCC
6 changed files with 65 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/content/en-US/02-lay-of-the-land/04-channels-support/index.adoc
View File

@ -15,21 +15,5 @@ The entry point is found at github:{github-repo}[`./default.nix`, path=./default
include::../../../../../default.nix[] include::../../../../../default.nix[]
---- ----
However, you have to keep some limitations and guidelines in mind. As you can tell, it is made with github:edolstra/flake-compat[opts=repo].
This is to support both use cases easily at the expense of making the traditional method a bit more tedious such as the Nix project being completely locked in with its dependencies (thus you can't configure it with your own nixpkgs version). footnote:[Then again, the way it used to be before flakes already has a host of problems. This is the least of them.]
* It exports an attribute based from the github:nix-community/NUR/[NUR template].
+
--
Several exports includes...
* My custom library at `lib`.
* Custom NixOS modules at `modules`.
* Custom home-manager modules at `hmModules`.
* An overlay of my custom packages at `overlays.foo-dogsquared-pkgs`.
* My packages as the rest of the top-level attributes from the attrset.
--
* Keep in mind it doesn't export the NixOS hosts and home-manager user configurations.
It would be pointless as it is duplicating effort plus **I really like managing my NixOS config more with the flakes way** compared to setting up channels.
It has a lot of advantages such as the ease of provisioning and updating your setups along with its dependencies, enforcing certain values in a certain attribute that can be seen in the revised Nix CLI, and nicer interface overall.
While possible with channels, this is just better experience overall and I have no interest in maintaining setups in both ways.

93
docs/content/en-US/03-project-specific-setup/01-declarative-host-management/index.adoc
View File

@ -4,87 +4,62 @@ title: Declarative host management
= Declarative host management = Declarative host management
This project uses a custom setup for declarative host management. This project uses a custom setup for declarative host management.
Specifically, it is done with a simple file at github:{github-repo}[`./setups/nixos.nix`, path=./setups/nixos.nix, rev=master] where it expects an attribute set of the hosts' metadata. It is a custom github:hercules-ci/flake-parts[opts=repo] module that allows you to easily initialize NixOS systems of multiple platforms (with multiple images output) while making it purely-built as much as possible.
Each host in the set represents one of the hosts at github:{github-repo}[`./hosts/`, path=./hosts/, rev=master].
Each of declared hosts are then exported as part of the `images` flake output attribute where each is a derivation for building them as an image output. This custom flake-parts modules integrates the following projects:
* It automatically adds github:serokell/deploy-rs[opts=repo] nodes ready to be deployed with `deploy` CLI tool.
* Mandatory inclusion of github:nix-community/home-manager[opts=repo].
* Image output generation made easy with github:nix-community/nixos-generators[opts=repo].
Each of the declared hosts are then exported either as part of the `images` or `nixosConfigurations` (or both) flake output attribute.
The `images` flake output attribute contains a per-system set of packages of the NixOS systems as the indicated package format.
For example, you can build my personalized NixOS installer ISO with the following command. For example, you can build my personalized NixOS installer ISO with the following command.
[source, shell, subs=attributes] [source, shell, subs=attributes]
---- ----
nix build {canonical-flake-url}#images.x86_64-linux.bootstrap nix build {canonical-flake-url}#images.x86_64-linux.bootstrap-iso
---- ----
[NOTE] This is an example of a declarative NixOS setup.
==== The following configuration should have the following effects in the flake output:
Not every image listed here is not meant to be built as a certain output but rather deployed somewhere else.
We'll see to specify it in the following section.
====
A host metadata has a certain schema which the following example is a complete version of it. * Two additional NixOS configurations to be deployed at `nixosConfigurations.plover-{x86_64-linux,aarch64-linux}`.
The data is then used for certain functions in the flake definition file (i.e., `flake.nix`). By default, declarative NixOS setups are not added automatically to `nixosConfigurations` output unless we have `configs.<config>.formats = null;` but we did configure `configs.<config>.deploy` so that makes it even.
* Four additional derivations added in `images` flake output (since there's 2 formats and 2 platforms) at `images.{x86_64-linux,aarch64-linux}.plover-{do,gce}`.
[#lst:images-metadata-example] [#lst:images-metadata-example]
[source, nix] [source, nix]
---- ----
{ {
plover = { setups.nixos.configs.plover = {
systems = [ "x86_64-linux" "aarch64-linux" ]; systems = [ "x86_64-linux" "aarch64-linux" ];
format = null; formats = [ "do" "gce" ];
domain = "foodogsquared.one"; domain = "foodogsquared.one";
nixpkgs-channel = "nixos-unstable-small"; nixpkgs-branch = "nixos-unstable-small";
home-manager-channel = "home-manager-unstable"; home-manager-branch = "home-manager-unstable";
modules = [ modules = [
({ config, lib, ... }: { ({ config, lib, ... }: {
services.foo.enable = true; services.foo.enable = true;
}) })
]; ];
overlays = [
inputs.neovim-nightly-overlay.overlays.default
];
deploy = { deploy = {
hostname = "plover.foodogsquared.one"; fastConnection = true;
ssh-user = "admin"; autoRollback = true;
fast-connection = true; magicRollback = true;
auto-rollback = true; remoteBuild = true;
magic-rollback = true; profiles = os: {
remote-build = true; system = {
sshUser = "root";
user = "admin";
path = inputs.deploy.lib.${os.system}.activate.nixos os.config;
};
};
}; };
}; };
} }
---- ----
For a complete reference, here are the expected attributes.
- `systems` contains a list of platforms of the host system.
This is mainly used to indicate the platform used for the nixpkgs repository.
- `format` is the image output format for the host.
It expects an accepted value from github:nix-community/nixos-generators[opts=repo] project.
To include a host as part of `nixosConfigurations`, you'll have to set this as `null`.
- `hostname` is the canonical hostname for the host.
If unset, the hostname is the name of the table key.
In the <<lst:images-metadata-example, previous example>>, if `plover.hostname` is unset, the value would be `plover` instead of `ploverrific`.
- `domain` is the domain used for networking configuration.
It is set for `networking.domain` in NixOS configuration.
- `nixpkgs-channel` is the nixpkgs channel to be used for the host.
The value could be any one of the nixpkgs flake inputs imported into this flake.
By default, it uses `nixpkgs` flake input which points to the `nixos-unstable` channel.
- `home-manager-channel` is the home-manager channel to be used for the host.
The value could be any one of the home-manager flake inputs imported into this flake.
By default, it uses `home-manager` flake input which follows the `home-manager-unstable` channel.
- `modules` is an extra list of modules to be imported with the configuration.
- `deploy` is a table containing arguments from github:serokell/deploy-rs[opts=repo].
Only a few arguments are accepted (i.e., `hostname`, `fast-connection`, `remote-build`, `magic-rollback`, and `auto-rollback`).
Once this attribute is present, it will be included as part of `nixosConfigurations` flake output no matter what `format` is given.
Those imported NixOS configurations are also exported as part of the deploy nodes for deploy-rs with the `nixos` prefix.
For example, here's the command to deploy my Plover server.
[source, shell, subs=attributes]
----
deploy {canonical-flake-url}#nixos-plover
----

55
docs/content/en-US/03-project-specific-setup/02-declarative-user-management/index.adoc
View File

@ -4,10 +4,9 @@ title: Declarative user management
= Declarative user management = Declarative user management
Similarly to xref:../01-declarative-host-management/index.adoc[Declarative host management], this project also provides a way to declare home-manager users. Similarly to xref:../01-declarative-host-management/index.adoc[Declarative host management], this project also provides a way to declare home-manager users.
The `./setups/home-manager.nix` sits in the project root expecting certain data. This is also presented as a custom flake-parts module as well, ready to be configured at `setups.home-manager` namespace of the flake-parts config.
Similar to the declarative NixOS setup, it expects an attribute set of users with each representing one of the users from github:{github-repo}[`./users/home-manager/`, path=./users/home-manager/, rev=master].
These are then included as part of `homeConfigurations` for easier installation with the standalone home-manager tool. This module is a bit simpler that it only makes configured users to be added to `homeConfigurations` and `deploy.nodes`.
Of which they are then included as part of deploy nodes for deploy-rs (also for easier deployment).
Here's an example user with complete schema. Here's an example user with complete schema.
@ -15,10 +14,15 @@ Here's an example user with complete schema.
[source, nix] [source, nix]
---- ----
{ {
foo-dogsquared = { setups.home-manager.sharedModules = [
systems = [ "x86_64-linux" ]; inputs.your-mom.homeModules.default
nixpkgs-channel = "nixos-stable"; ];
home-manager-channel = "home-manager-23.05";
# Here is the meat, what you're likely going to do.
setups.home-manager.configs.foo-dogsquared = {
systems = [ "x86_64-linux" "aarch64-linux" ];
nixpkgs-branch = "nixos-stable";
home-manager-branch = "home-manager-23.05";
home-directory = "/home/foo-dogsquared"; home-directory = "/home/foo-dogsquared";
username = "foodogsquared"; username = "foodogsquared";
modules = [ modules = [
@ -26,37 +30,16 @@ Here's an example user with complete schema.
services.foo.enable = true; services.foo.enable = true;
}) })
]; ];
overlays = [
inputs.neovim-nightly-overlay.overlays.default
];
deploy = { deploy = {
hostname = "local.foodogsquared.one"; hostname = "local.foodogsquared.one";
ssh-user = "admin"; fastConnection = true;
profile = "foodogsquared"; autoRollback = true;
fast-connection = true; magicRollback = true;
auto-rollback = true; remoteBuild = true;
magic-rollback = true;
remote-build = true;
}; };
}; };
} }
---- ----
- `systems` contains a list of platforms of the home-manager user.
This is mainly used to indicate the platform used for the nixpkgs repository.
- `nixpkgs-channel` indicates the branch of the nixpkgs to be used.
By default, this uses the `nixpkgs` which follows the `nixos-unstable` branch.
- `home-manager-channel` contains the home-manager channel to be used.
The value should be one of the home-manager channel that is imported into this flake.
By default, it sets the home-manager channel at `home-manager` which is pointed at the unstable channel.
- `home-directory` is the associated home directory of the home-manager.
It is set for `config.home.directory` at the home-manager configuration.
By default, it will be set at `/home/$USERNAME`.
- `username` is the username of the home-manager user to be used for `config.home.username` at the home-manager configuration.
If unset, it will use the table key.
In the above example, the unset value would be `foo-dogsquared`.
- `modules` is an extra list of modules to be imported with the configuration.
- `deploy` is pretty similar to the previous configuration setting that it sets certain options for deploy-rs.

2
docs/content/en-US/04-nixos-modules/03-disko/index.adoc
View File

@ -13,7 +13,7 @@ Here's an example configuration for my desktop workstation.
.`./hosts/ni/disko.nix` .`./hosts/ni/disko.nix`
[source, nix] [source, nix]
---- ----
include::../../../../../hosts/ni/disko.nix[] include::../../../../../configs/nixos/ni/disko.nix[]
---- ----
Take note the disko NixOS module already handles NixOS filesystem configuration (i.e., `fileSystems.<name>`) so if you have already have an existing hardware configuration, you have to delete it to prevent conflicting fstab configuration. Take note the disko NixOS module already handles NixOS filesystem configuration (i.e., `fileSystems.<name>`) so if you have already have an existing hardware configuration, you have to delete it to prevent conflicting fstab configuration.

22
docs/content/en-US/06-using-parts-of-my-configuration/index.adoc
View File

@ -56,9 +56,7 @@ In that case, you can simply plop them into your list of imports for your NixOS
---- ----
{ {
imports = [ imports = [
inputs.foo-dogsquared-nixos-config.nixosModules.programs inputs.foo-dogsquared-nixos-config.nixosModules.default
inputs.foo-dogsquared-nixos-config.nixosModules.services
inputs.foo-dogsquared-nixos-config.nixosModules.workflows
]; ];
# Use my GNOME desktop configuration for some reason. # Use my GNOME desktop configuration for some reason.
@ -87,22 +85,20 @@ nix-channel --update
[source, nix] [source, nix]
---- ----
import <foo-dogsquared-nixos-config> { inherit pkgs; } import <foo-dogsquared-nixos-config> { }
---- ----
You can see github:{github-repo}[`./default.nix`, path=default.nix, rev=master] to see more details but there are general guidelines to the attributes that is contained in this file which is outlined in xref:../02-lay-of-the-land/04-channels-support/index.adoc[Channels support] section. This is made with flake-compat flake which can have conflicts with the traditional method of using it.
Here's an example snippet in a NixOS config making use of my configuration without flakes: Here's an example snippet in a NixOS config making use of my configuration without flakes:
[source, nix] [source, nix]
---- ----
let let
foo-dogsquared-nixos-config = import <foo-dogsquared-nixos-config> { inherit pkgs; }; foo-dogsquared-nixos-config = import <foo-dogsquared-nixos-config> { };
in { in {
imports = [ imports = [
foo-dogsquared-nixos-config.modules.programs foo-dogsquared-nixos-config.nixosModules.default
foo-dogsquared-nixos-config.modules.services
foo-dogsquared-nixos-config.modules.workflows
]; ];
# Still using my GNOME desktop configuration for some reason. # Still using my GNOME desktop configuration for some reason.
@ -122,15 +118,13 @@ Here's a snippet of using it as part of a NixOS configuration.
[source, nix] [source, nix]
---- ----
let let
foo-dogsquared-nixos-config = import (fetchTarball "{canonical-flake-url-tarball-specific}") { inherit pkgs; }; foo-dogsquared-nixos-config = import (fetchTarball "{canonical-flake-url-tarball-specific}") { };
in { in {
imports = [ imports = [
foo-dogsquared-nixos-config.modules.programs foo-dogsquared-nixos-config.nixosModules.default
foo-dogsquared-nixos-config.modules.services
foo-dogsquared-nixos-config.modules.workflows
]; ];
# Still using my GNOME desktop configuration for some reason. # GNOME4LIFE!!!
workflows.workflows.a-happy-gnome.enable = true; workflows.workflows.a-happy-gnome.enable = true;
} }
---- ----

2
docs/content/en-US/08-acknowledgement/index.adoc
View File

@ -20,4 +20,4 @@ I may have to use this at some point. footnote:[Unfortunately, digga is consider
* github:hlissner/dotfiles/[hlissner's dotfiles], the original inspiration for this functional abomination of a configuration. * github:hlissner/dotfiles/[hlissner's dotfiles], the original inspiration for this functional abomination of a configuration.
The very reason why I'm using NixOS after seeing their configuration and what it can be setup with one command. The very reason why I'm using NixOS after seeing their configuration and what it can be setup with one command.
Very nice. Anyways, screw you for bringing me into this [.line-through]#hell# rabbit hole.