mirror of
https://github.com/foo-dogsquared/nixos-config.git
synced 2025-01-30 22:57:55 +00:00
docs/site: write "The lay of the land" chapter
This commit is contained in:
parent
ff8451f0b2
commit
3a00738bf7
107
README.adoc
107
README.adoc
@ -54,113 +54,6 @@ To install it, run the `nixos-install --flake {canonical_flake_url}#ni`.
|
||||
(Please see the respective appropriate host README for more information.)
|
||||
|
||||
|
||||
[#channels-support]
|
||||
=== Channels support
|
||||
|
||||
While this primarily uses flakes as its main form of distribution, this project does keep some use cases for traditional channels.
|
||||
It's not guaranteed to be good as using it <<using-my-config-with-flakes>> but it's an option.
|
||||
|
||||
The entry point is found at link:./default.nix[`./default.nix`].
|
||||
However, you have to keep some limitations and guidelines in mind.
|
||||
|
||||
* It exports an attribute based from the link:https://github.com/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.
|
||||
|
||||
|
||||
[#whats-in-my-flake]
|
||||
=== What's in my flake?
|
||||
|
||||
You can see the full details with `nix flake show`.
|
||||
As a helpful summary, here's what my flake should contain sorting from the most interesting and helpful outputs to the most boring and unnecessary.
|
||||
|
||||
* `packages` contains link:./pkgs[my custom packages] and some of usual images of several hosts which is nice for easily fetching custom images.
|
||||
|
||||
* `overlays` contains the overlay for extending nixpkgs with my packages.
|
||||
If you want to use my packages alongside the nixpkgs attribute then this is what you're looking for.
|
||||
|
||||
* `homeModules` are where my link:./modules/home-manager[custom home-manager modules] to be exported.
|
||||
footnote:[This is more useful than my NixOS modules.]
|
||||
|
||||
* `nixosModules` are composed from NixOS modules defined in link:./modules/nixos[`./modules/nixos`].
|
||||
It can be used as additional modules for your own NixOS config in case you want to use mine for whatever reason.
|
||||
There are some niceties in there.
|
||||
+
|
||||
--
|
||||
A few examples include:
|
||||
|
||||
* A NixOS module for Pop launcher plugins and scripts.
|
||||
* Several service modules for archiving with link:https://github.com/yt-dlp/yt-dlp[yt-dlp], link:https://github.com/mikf/gallery-dl/[gallery-dl], and link:https://archivebox.io/[ArchiveBox].
|
||||
* My themes which contain full desktop environments which is nice for quickly initializing a NixOS configuration.
|
||||
--
|
||||
|
||||
* `devShells` from link:./shells/[my custom environments].
|
||||
Similar to `homeConfigurations`, you can easily use it outside of NixOS.
|
||||
|
||||
* `homeConfigurations` contains my various link:https://github.com/nix-community/home-manager[home-manager] configurations from link:./users/home-manager/[`./users/home-manager/`].
|
||||
The neat thing about it is you can easily install it in a non-NixOS Linux distro.
|
||||
|
||||
* `deploy` are nodes to be deployed by link:https://github.com/serokell/deploy-rs[deploy-rs].
|
||||
It's nice and currently not all of the nodes are publicly committed which is less useful but it'll be someday.
|
||||
|
||||
* `nixosConfigurations` which is where you can install my various NixOS configurations directly (e.g., `nixos-install --flake {canonical_flake_url}#HOST`).
|
||||
This mainly uses the link:./hosts/[hosts configuration].
|
||||
|
||||
* `templates` which contains my templates.
|
||||
Though, these are just templates mostly for my own purposes so it is not as useful as the other outputs.
|
||||
|
||||
* `hydraJobs` contains link:https://github.com/NixOS/hydra[Hydra] build jobs where it is primarily used for my test Hydra instance.
|
||||
|
||||
* `lib` is defined from link:./lib/[my custom library].
|
||||
It mainly assumes it is to be included in nixpkgs standard library (i.e., `import ./lib { lib = inputs.nixpkgs.lib; }`).
|
||||
It's another unnecessary export but it's there.
|
||||
|
||||
* `formatter` is the preferred formatter to be used for my Nix files.
|
||||
Nothing special here.
|
||||
|
||||
* `checks` contains checks for several outputs and are mainly for internal purposes.
|
||||
There's no use for anyone else, really. :(
|
||||
|
||||
|
||||
=== What should not be here?
|
||||
|
||||
Despite being a NixOS configuration, this is not meant to be fully reproducible by anyone.
|
||||
There are still some things that would need to be privately held as indicated by the following list.
|
||||
|
||||
- Associated private keys: GPG, SSH, age, you name it.
|
||||
They are used with a secret management tool (see <<secrets-management>> for more information) to encrypt the more sensitive parts of the system such as credentials and environment files.
|
||||
|
||||
- Disposable hosts configurations.
|
||||
They will typically just make a messier mess than the current situation.
|
||||
|
||||
Though the unreproducible part is only like 10% of the whole configuration, it can be successfully deployed by anyone.
|
||||
Keep in mind, it comes with a few restrictions due to the lack of the appropriate credentials.
|
||||
|
||||
- Certain tasks will not start.
|
||||
Most of the project tasks found in this repo requires the associated private key with the task.
|
||||
An example would be the link:./modules/nixos/tasks/backup-archive[Borg backup task] where it needs several files and credentials locked from the secrets management tool.
|
||||
|
||||
- Certain components will be missing.
|
||||
Most notably, the associated SSH key for the hosts.
|
||||
You won't be able to connect to the host if you don't have the private key.
|
||||
|
||||
- Not to mention not all modules listed committed here are up-to-date.
|
||||
Though this only applies to non-critical services like the link:./modules/nixos/tasks/multimedia-archive[multimedia archiving service].
|
||||
|
||||
|
||||
=== The remote repo
|
||||
|
||||
For a complete overkill, we use a CI to further the configuration abomination.
|
||||
|
||||
@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Channels support
|
||||
---
|
||||
= Channels support
|
||||
|
||||
While this primarily uses flakes as its main form of distribution, this project does keep some use cases for traditional channels.
|
||||
It's not guaranteed to be good as xref:../../using-parts-of-my-configuration/index.adoc#using-my-config-with-flakes[Using my config with flakes] but it's an option.
|
||||
Anyhow, there is a section for using my configuration with channels as shown in xref:../../using-parts-of-my-configuration/index.adoc#using-my-config-with-channels[Using my config with channels].
|
||||
|
||||
The entry point is found at github:{github-repo}[`./default.nix`, path=./default.nix, rev=master].
|
||||
However, you have to keep some limitations and guidelines in mind.
|
||||
|
||||
* 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.
|
||||
37
docs/content/en-US/lay-of-the-land/prerequisites/index.adoc
Normal file
37
docs/content/en-US/lay-of-the-land/prerequisites/index.adoc
Normal file
@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Prerequisites
|
||||
---
|
||||
= Prerequisites
|
||||
|
||||
Before you get into dive into this configuration, let's establish a few things first.
|
||||
In order to make use of this system in the first place, you need the following components.
|
||||
|
||||
- A NixOS installer image with flakes enabled.
|
||||
An example would be the unstable versions from link:https://releases.nixos.org/?prefix=nixos/unstable/[NixOS project release page].
|
||||
As an additional option, you can also use link:https://github.com/foo-dogsquared/nixos-config/releases/tag/latest[my personalized NixOS installers] which is primarily intended for me configs.
|
||||
|
||||
- A flash drive or any storage device that will boot the installer image up for installation.
|
||||
|
||||
- A computer with disabled secure boot.
|
||||
Because unfortunately, that's the state of most Linux distros right now. footnote:[But things change hopefully with github:nix-community/lanzaboote[Lanzaboote project] into usable and stable state.]
|
||||
|
||||
This primarily uses Nix flakes so you can have a preview of what's available in my config.
|
||||
|
||||
[source, shell, subs=attributes]
|
||||
----
|
||||
nix flake show {canonical-flake-url}
|
||||
----
|
||||
|
||||
All you have to do is to flash the installer image into the flash drive and boot with the drive (with the disabled secure boot).
|
||||
Then run the following command in the shell as root.
|
||||
|
||||
[source, shell, subs=attributes]
|
||||
----
|
||||
nixos-install --flake {canonical-flake-url}#INSTALLABLE
|
||||
----
|
||||
|
||||
Despite being a NixOS system, it isn't entirely reproducible to the point of installing this config will work out-of-the-box.
|
||||
It has some things needed in the first place to work like my external backup setup where it needs my SSH private keys to work in the first place.
|
||||
You can see more details from xref:../what-should-not-be-here/index.adoc[What should not be here?].
|
||||
Nonetheless, the parts is it isn't reproducible is only about 10% of this config.
|
||||
Everything else is fine and dandy and can be deployed successfully (but not used as intended).
|
||||
@ -0,0 +1,62 @@
|
||||
---
|
||||
title: Project structure
|
||||
---
|
||||
= Project structure
|
||||
|
||||
Last and foremost, we have the project directory — the environment you'll be living in for the next year, tinkering your Nix configs.
|
||||
.
|
||||
It is required to be familiar with the workspace, after all.
|
||||
My configuration takes a lot of cues from link:{devos_link}[devos] (which is unfortunately is a lot to take if you're just beginning to grok Nix as a whole).
|
||||
|
||||
My NixOS config should look like the following:
|
||||
|
||||
[source, tree]
|
||||
----
|
||||
nixos-config
|
||||
├── hosts/
|
||||
├── lib/
|
||||
├── modules/
|
||||
├── pkgs/
|
||||
├── scripts/
|
||||
├── secrets/
|
||||
├── shells/
|
||||
├── templates/
|
||||
├── users/
|
||||
├── default.nix
|
||||
├── flake.lock
|
||||
├── flake.nix
|
||||
├── images.toml
|
||||
└── README.adoc
|
||||
----
|
||||
|
||||
One of the more notable files here when first start looking is the link:./images.toml[`./images.toml`] file where it contains a description of the images.
|
||||
For more details, see <<declarative-host-management>>.
|
||||
|
||||
Most of the said folders are related to a flake output attribute, see <<whats-in-my-flake>> for more details.
|
||||
|
||||
* link:./hosts/[`./hosts/`] contain machine-specific configuration.
|
||||
This usually configures like the hardware setup, timezone, and users.
|
||||
Host configurations are also exported in the flakes in `outputs.nixosConfigurations`.
|
||||
|
||||
* link:./modules/[`./modules/`] contain my custom modules including NixOS and home-manager modules.
|
||||
For more information, see the link:./modules/README.adoc[related documentation].
|
||||
|
||||
* link:./pkgs/[`./pkgs/`] contains my custom packages.
|
||||
It is exported in the flakes at `outputs.packages` compiled through various systems.
|
||||
|
||||
* link:./scripts/[`./scripts/`] contains various scripts for various purposes.
|
||||
Should be self-explanatory.
|
||||
|
||||
* link:./secrets/[`./secrets/`] contains my cluster-wide secrets managed with link:https://github.com/mozilla/sops[sops] and link:https://github.com/Mic92/sops-nix[sops-nix].
|
||||
Take note, each component (e.g., hosts, modules, users) could have their own specific secrets.
|
||||
|
||||
* link:./shells/[`./shells/`] contains my development shells for interacting with the usual type of projects.
|
||||
Setting this up can bring benefits outside of NixOS (unless you're interacting with projects with any OpenGL-related stuff).
|
||||
footnote:[Since packages brought from Nix shells can only work with the store, a container might be better at some situations.]
|
||||
|
||||
* link:./templates/[`./templates/`] contains my custom templates handy for quickly initializing for various types of projects.
|
||||
|
||||
* link:./users/[`./users/`] contains my link:https://github.com/nix-community/home-manager[home-manager] configurations.
|
||||
It is exported in the flakes at `outputs.homeConfigurations`.
|
||||
For more information, see the link:./users/README.adoc[related documentation].
|
||||
|
||||
@ -0,0 +1,27 @@
|
||||
---
|
||||
title: What should not be here?
|
||||
---
|
||||
= What should not be here?
|
||||
|
||||
Despite being a NixOS configuration, this is not meant to be fully reproducible by anyone.
|
||||
There are still some things that would need to be privately held as indicated by the following list.
|
||||
|
||||
- Associated private keys: GPG, SSH, age, you name it.
|
||||
They are used with a secret management tool (see xref:../../project-specific-setup/secrets-management/index.adoc[Secret management] for more information) to encrypt the more sensitive parts of the system such as credentials and environment files.
|
||||
|
||||
- Disposable hosts configurations.
|
||||
They will typically just make a messier mess than the current situation.
|
||||
|
||||
Though the unreproducible part is only like 10% of the whole configuration, it can be successfully deployed by anyone.
|
||||
Keep in mind, it comes with a few restrictions due to the lack of the appropriate credentials.
|
||||
|
||||
- Certain tasks will not start.
|
||||
Most of the project tasks found in this repo requires the associated private key with the task.
|
||||
An example would be the github:{github-repo}[Borg backup task, path=./modules/nixos/tasks/backup-archive, rev=master] where it needs several files and credentials locked from the secrets management tool.
|
||||
|
||||
- Certain components will be missing.
|
||||
Most notably, the associated SSH key for the hosts.
|
||||
You won't be able to connect to the host if you don't have the private key.
|
||||
|
||||
- Not to mention not all modules listed committed here are up-to-date.
|
||||
Though this only applies to non-critical services like the github:{github-repo}[multimedia archiving service, path=./modules/nixos/tasks/multimedia-archive, rev=master].
|
||||
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: What's in my flake?
|
||||
---
|
||||
= What's in my flake?
|
||||
|
||||
You can see the full details with `nix flake show`.
|
||||
As a helpful summary, here's what my flake should contain sorting from the most interesting and helpful outputs to the most boring and unnecessary.
|
||||
|
||||
* `packages` contains github:{github-repo}[my custom packages, path=./pkgs, rev=master] and some of usual images of several hosts which is nice for easily fetching custom images.
|
||||
|
||||
* `overlays` contains the overlay for extending nixpkgs with my packages.
|
||||
If you want to use my packages alongside the nixpkgs attribute then this is what you're looking for.
|
||||
|
||||
* `homeModules` are where my github:{github-repo}[custom home-manager modules, path=./modules/home-manager, rev=master] to be exported.
|
||||
footnote:[This is more useful than my NixOS modules.]
|
||||
|
||||
* `nixosModules` are composed from NixOS modules defined in github:{github-repo}[`./modules/nixos`, path=./modules/nixos, rev=master].
|
||||
It can be used as additional modules for your own NixOS config in case you want to use mine for whatever reason.
|
||||
There are some niceties in there.
|
||||
+
|
||||
--
|
||||
A few examples include:
|
||||
|
||||
* A NixOS module for Pop launcher plugins and scripts.
|
||||
* Several service modules for archiving with github:yt-dlp/yt-dlp[opts=repo], github:mikf/gallery-dl[opts=repo], and link:https://archivebox.io/[ArchiveBox].
|
||||
* My themes which contain full desktop environments which is nice for quickly initializing a NixOS configuration.
|
||||
--
|
||||
|
||||
* `devShells` from github:{github-repo}[my custom environments, path=./shells, rev=master].
|
||||
Similar to `homeConfigurations`, you can easily use it outside of NixOS.
|
||||
|
||||
* `homeConfigurations` contains my various github:nix-community/home-manager[opts=repo] configurations from link:{github-repo}[`./users/home-manager/`, path=./users/home-manager/, rev=master].
|
||||
The neat thing about it is you can easily install it in a non-NixOS Linux distro.
|
||||
|
||||
* `deploy` are nodes to be deployed by github:serokell/deploy-rs[opts=repo].
|
||||
It's nice and currently not all of the nodes are publicly committed which is less useful but it'll be someday.
|
||||
|
||||
* `nixosConfigurations` which is where you can install my various NixOS configurations directly (e.g., `nixos-install --flake {canonical-flake-url}#HOST`).
|
||||
This mainly uses the github:{github-repo}[hosts configuration, path=./hosts, rev=master].
|
||||
|
||||
* `templates` which contains my templates.
|
||||
Though, these are just templates mostly for my own purposes so it is not as useful as the other outputs.
|
||||
|
||||
* `hydraJobs` contains github:NixOS/hydra[Hydra] build jobs where it is primarily used for my test Hydra instance.
|
||||
|
||||
* `lib` is defined from github:{github-repo}[my custom library, path=./lib, rev=master].
|
||||
It mainly assumes it is to be included in nixpkgs standard library (i.e., `import ./lib { lib = inputs.nixpkgs.lib; }`).
|
||||
It's another unnecessary export but it's there.
|
||||
|
||||
* `formatter` is the preferred formatter to be used for my Nix files.
|
||||
Nothing special here.
|
||||
|
||||
* `checks` contains checks for several outputs and are mainly for internal purposes.
|
||||
There's no use for anyone else, really. :(
|
||||
@ -1,10 +1,10 @@
|
||||
* link:{{< relref "./introduction/" >}}[Introduction]
|
||||
|
||||
* The lay of the land
|
||||
** link:./lay-of-the-land/prerequisites/[Prerequisites]
|
||||
** link:./lay-of-the-land/channels-support[Channels support]
|
||||
** link:./lay-of-the-land/whats-in-my-flake[What's in my flake?]
|
||||
** link:./lay-of-the-land/what-should-not-be-here[What should not be here?]
|
||||
** link:{{< relref "./lay-of-the-land/prerequisites/" >}}[Prerequisites]
|
||||
** link:{{< relref "./lay-of-the-land/whats-in-my-flake/" >}}[What's in my flake?]
|
||||
** link:{{< relref "./lay-of-the-land/channels-support/" >}}[Channels support]
|
||||
** link:{{< relref "./lay-of-the-land/what-should-not-be-here/" >}}[What should not be here?]
|
||||
|
||||
* Project-specific setup
|
||||
** link:./project-specific-setup/declarative-host-management[Declarative host management]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user