diff --git a/README.adoc b/README.adoc index 88e4f1a1..72853ca8 100644 --- a/README.adoc +++ b/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 <> 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 <> 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. diff --git a/docs/content/en-US/lay-of-the-land/channels-support/index.adoc b/docs/content/en-US/lay-of-the-land/channels-support/index.adoc new file mode 100644 index 00000000..862f7bcd --- /dev/null +++ b/docs/content/en-US/lay-of-the-land/channels-support/index.adoc @@ -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. diff --git a/docs/content/en-US/lay-of-the-land/prerequisites/index.adoc b/docs/content/en-US/lay-of-the-land/prerequisites/index.adoc new file mode 100644 index 00000000..9feb2cd9 --- /dev/null +++ b/docs/content/en-US/lay-of-the-land/prerequisites/index.adoc @@ -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). diff --git a/docs/content/en-US/lay-of-the-land/project-structure/index.adoc b/docs/content/en-US/lay-of-the-land/project-structure/index.adoc new file mode 100644 index 00000000..48816ad9 --- /dev/null +++ b/docs/content/en-US/lay-of-the-land/project-structure/index.adoc @@ -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 <>. + +Most of the said folders are related to a flake output attribute, see <> 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]. + diff --git a/docs/content/en-US/lay-of-the-land/what-should-not-be-here/index.adoc b/docs/content/en-US/lay-of-the-land/what-should-not-be-here/index.adoc new file mode 100644 index 00000000..aa97388b --- /dev/null +++ b/docs/content/en-US/lay-of-the-land/what-should-not-be-here/index.adoc @@ -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]. diff --git a/docs/content/en-US/lay-of-the-land/whats-in-my-flake/index.adoc b/docs/content/en-US/lay-of-the-land/whats-in-my-flake/index.adoc new file mode 100644 index 00000000..6830f106 --- /dev/null +++ b/docs/content/en-US/lay-of-the-land/whats-in-my-flake/index.adoc @@ -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. :( diff --git a/docs/content/en-US/menu.adoc b/docs/content/en-US/menu.adoc index 26998b6f..127ff093 100644 --- a/docs/content/en-US/menu.adoc +++ b/docs/content/en-US/menu.adoc @@ -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]