From bf34d2071ff1f660156cd9cb2c79988d6f0afb3b Mon Sep 17 00:00:00 2001 From: Timothy DeHerrera Date: Sat, 13 Feb 2021 19:38:20 -0700 Subject: [PATCH] doc: new mdbook documentation --- .github/workflows/mdbook_docs.yml | 26 +++++++ .gitignore | 1 + CONTRIBUTING.md | 18 ----- DOC.md | 105 -------------------------- SUMMARY.md | 19 +++++ book.toml | 9 +++ cachix/README.md | 12 +++ doc/.gitignore | 1 + doc/flk/index.md | 1 + doc/introduction.md | 33 ++++++++ doc/layout.md | 4 + doc/start/from-nixos.md | 47 ++++++++++++ doc/start/index.md | 38 ++++++++++ doc/start/iso.md | 11 +++ extern/README.md | 10 +++ extern/default.nix | 2 +- flake.lock | 6 +- flake.nix | 8 +- hosts/README.md | 43 +++++++++++ hosts/default.nix | 13 ++-- lib/default.nix | 8 +- modules/README.md | 79 +++++++++++++++++++ modules/{list.nix => module-list.nix} | 0 overlays/.gitkeep | 0 overlays/README.md | 25 ++++++ overrides/README.md | 46 +++++++++++ {unstable => overrides}/default.nix | 7 +- pkgs/README.md | 59 +++++++++++++++ profiles/README.md | 48 ++++++++++++ secrets/.gitattributes | 1 + secrets/README.md | 18 +++++ shell/default.nix | 1 - suites/README.md | 24 ++++++ users/README.md | 51 +++++++++++++ 34 files changed, 627 insertions(+), 147 deletions(-) create mode 100644 .github/workflows/mdbook_docs.yml delete mode 100644 CONTRIBUTING.md delete mode 100644 DOC.md create mode 100644 SUMMARY.md create mode 100644 book.toml create mode 100644 cachix/README.md create mode 100644 doc/.gitignore create mode 100644 doc/flk/index.md create mode 100644 doc/introduction.md create mode 100644 doc/layout.md create mode 100644 doc/start/from-nixos.md create mode 100644 doc/start/index.md create mode 100644 doc/start/iso.md create mode 100644 extern/README.md create mode 100644 hosts/README.md create mode 100644 modules/README.md rename modules/{list.nix => module-list.nix} (100%) delete mode 100644 overlays/.gitkeep create mode 100644 overlays/README.md create mode 100644 overrides/README.md rename {unstable => overrides}/default.nix (73%) create mode 100644 pkgs/README.md create mode 100644 profiles/README.md create mode 100644 secrets/README.md create mode 100644 suites/README.md create mode 100644 users/README.md diff --git a/.github/workflows/mdbook_docs.yml b/.github/workflows/mdbook_docs.yml new file mode 100644 index 0000000..775d52c --- /dev/null +++ b/.github/workflows/mdbook_docs.yml @@ -0,0 +1,26 @@ +name: Deploy Docs to GitHub Pages + +on: + push: + branches: + - doc + +jobs: + deploy: + runs-on: ubuntu-18.04 + steps: + - uses: actions/checkout@v2 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v1 + with: + mdbook-version: 'latest' + + - run: mdbook build + + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages + publish_dir: ./book diff --git a/.gitignore b/.gitignore index 4e131a1..509d869 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ result up hosts/up-* .direnv +book diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index a7fc9eb..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pull Requests - -While much of your work in this template may be idiosyncratic in nature. Anything -that might be generally useful to the broader NixOS community can be synced to -the `template` branch to provide a host of useful NixOS configurations available -"out of the box". If you wish to contribute such an expression please follow -these guidelines: - -* format your code with [`nixpkgs-fmt`][nixpkgs-fmt]. The default devshell - includes a pre-commit hook that does this for you. - -* The commit message follows the same semantics as [nixpkgs][nixpkgs]. - * You can use a `#` symbol to specify ambiguities. For example, - `develop#zsh: ` would tell me that your updating the - `zsh` subprofile living under the `develop` profile. - -[nixpkgs-fmt]: https://github.com/nix-community/nixpkgs-fmt -[nixpkgs]: https://github.com/NixOS/nixpkgs diff --git a/DOC.md b/DOC.md deleted file mode 100644 index e5c0a7a..0000000 --- a/DOC.md +++ /dev/null @@ -1,105 +0,0 @@ -## Hosts -Module declarations dependant on particular machines should be stored in the -[hosts](hosts) directory. Every file in this directory will be added automatically -to the the `nixosConfigurations` flake output and thus becomes deployable via -`nixos-rebuild` and `flk`. - -See [`hosts/default.nix`](hosts/default.nix) for the implementation. - -## Profiles -A profile is any directory under [profiles](profiles) containing a `default.nix` -defining a function that returns a valid NixOS module, with the added restriction -that no new declarations to the `options` _or_ `config` attributes are allowed -(use [modules](modules) instead). Their purpose is to provide abstract -expressions suitable for reuse by multiple deployments. They are perhaps _the_ -key mechanism by which we keep this repo maintainable. - -Profiles can have subprofiles which are themselves just profiles that live under -another. There's no hard rule that everything in the folder must be imported by -its `default.nix`, so you can also store relevant code that is useful but not -wanted by default in, say, an `alt.nix`. Importantly, every subdirectory in a -profile should be independent of its parent. i.e: - -```nix -{ - # importing `profile` without implicitly importing `some` - imports = [ ./profiles/some/profile ]; -} -``` - -It is okay for profiles to depend on other profiles so long as they are -explicitly loaded via `imports`. - -## Suites - -[Suites](./suites/default.nix) are simple collections of profiles that can be -directly imported from any host like so: -``` -{ suites, ... }: -{ - imports = suites.mySuite; -} -``` - -You can declare any combination of users and profiles that you wish, providing -a nice abstraction, free from the idiosyncratic concerns of specific hardware. - -## Users -User declarations belong in the `users` directory. - -These are actually just a special case of [profiles](#profiles) attached to -a particular interactive user. Its primarily for declarations to -`users.users.` where `.isNormalUser` is true. - -This is a convenient place to import your profiles such that a particular user -always has a reliable stack. Also [user profiles](./users/profiles) are -available to create reusable configs across different users. - -For convenience, [home-manager][home-manager] is available automatically for -home directory setup and should only be used from this directory. - -## Secrets -Anything you wish to keep encrypted goes in the `secrets` directory, which is -created on first entering a `nix-shell`. - -Be sure to run `git crypt init`, before committing anything to this directory. -Be sure to check out git-crypt's [documentation](https://github.com/AGWA/git-crypt) -if your not familiar. The filter is already set up to encrypt everything in this -folder by default. - -To keep [profiles](profiles) reusable across configurations, secrets should -only be imported from the `users` or [`hosts`](hosts) directory. - -## Cachix -When using: -``` -cachix use -``` -A file with be created in `/etc/nixos/cachix/your-cachix.nix`. Simply add this -file to git, and it will be exported so others can use your binary cache -directly from this flake via `nixosModules.cachix.`. - - -## Modules, Packages and Overlays -All expressions in both [modules/list.nix](modules/list.nix) and -[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the -repo. They are additionally included in the `nixosModules` and `overlay` flake -outputs, respectively. Packages are automatically included in the `packages` -output as well. - -The directory structure is identical to nixpkgs to provide a kind of staging area -for any modules or packages we might be wanting to merge there later. If your not -familiar or can't be bothered, simply dropping a valid nix file and pointing the -`default.nix` to it, is all that's really required. - -As for overlays, they should be defined in the [overlays](overlays) directory. -They will be automatically pulled in for use by all configurations. Nix command -line tools will be able to read overlays from here as well since it is set as -`nixpkgs-overlays` in `NIX_PATH`. And of course they will be exported via the -flake output `overlays` as well. - -If you wish to use an overlay from an external flake, simply add it to the -`externOverlays` list in the `let` block of the `outputs` attribute in -[flake.nix](flake.nix). Same for external modules, add them to `externModules`. - -[home-manager]: https://github.com/nix-community/home-manager diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..1b95eb5 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,19 @@ +# Summary + +- [Introduction](./doc/introduction.md) +- [Quick Start](./doc/start/index.md) + - [ISO](./doc/start/iso.md) + - [From NixOS](./doc/start/from-nixos.md) +- [Layout](./doc/layout.md) + - [Cachix](./cachix/README.md) + - [Extern](./extern/README.md) + - [Hosts](./hosts/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) + - [Users](./users/README.md) +- [flk command](./doc/flk/index.md) diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..e843940 --- /dev/null +++ b/book.toml @@ -0,0 +1,9 @@ +[book] +authors = ["Timothy DeHerrera"] +language = "en" +multilingual = false +src = "." +title = "nixflk docs" + +[output.html] +site-url = "/nixflk/" diff --git a/cachix/README.md b/cachix/README.md new file mode 100644 index 0000000..de732dc --- /dev/null +++ b/cachix/README.md @@ -0,0 +1,12 @@ +# Cachix +The cachix directory simple captures the output of `sudo cachix use` for the +developers personal cache, as well as the nix-community cache. You can easily +add your own cache, assuming the template lives in /etc/nixos, by simply +running `sudo cachix use yourcache`. + +These caches are only added to the system after a `nixos-rebuild switch`, so it +is recommended to call `cachix use nrdxp` before the initial deployment, as it +will save a lot of build time. + +In the future, users will be able to skip this step once the ability to define +the nix.conf within the flake is fully fleshed out upstream. diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +book diff --git a/doc/flk/index.md b/doc/flk/index.md new file mode 100644 index 0000000..6a44195 --- /dev/null +++ b/doc/flk/index.md @@ -0,0 +1 @@ +# flk command diff --git a/doc/introduction.md b/doc/introduction.md new file mode 100644 index 0000000..9f7b2bd --- /dev/null +++ b/doc/introduction.md @@ -0,0 +1,33 @@ +# Introduction +Nixflk is a template which grants a simple way to use, deploy and manage +[NixOS][nixos] systems for personal and productive use. It does this by +providing a sane repository structure, integrating several popular projects +like [home-manager][home-manager], setting clear guidelines, offering useful +conveniences, and eliminating boilerplate so you can focus on deploying your +systems. + +## Community Profiles +There are two branches from which to choose: [core][core] and +[community][community]. The community branch builds on core and includes +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. + +### ⚠ Advisory +Nixflk leverages the [flakes][flakes] feature available via an _experimental_ +branch of [nix][nix]. Until nix 3.0 is released, this project should be +considered unstable. + +# License +Nixflk is licensed under the [MIT License](https://mit-license.org). + +[nix]: https://nixos.org/manual/nix/stable +[nixos]: https://nixos.org/manual/nixos/stable +[home-manager]: https://nix-community.github.io/home-manager +[flakes]: https://nixos.wiki/wiki/Flakes +[core]: https://github.com/nrdxp/nixflk +[community]: https://github.com/nrdxp/nixflk/tree/community diff --git a/doc/layout.md b/doc/layout.md new file mode 100644 index 0000000..1883118 --- /dev/null +++ b/doc/layout.md @@ -0,0 +1,4 @@ +# 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. diff --git a/doc/start/from-nixos.md b/doc/start/from-nixos.md new file mode 100644 index 0000000..7c37cdc --- /dev/null +++ b/doc/start/from-nixos.md @@ -0,0 +1,47 @@ +# From NixOS + +## Generate Configuration +Assuming your happy with your existing partition layout, you can generate a +basic NixOS configuration for your system using: +```sh +flk up +``` + +This will make a new file `hosts/up-$(hostname).nix`, which you can edit to +your liking. + +Make sure your `i18n.defaultLocale` and `time.timeZone` are set properly for +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. + +> ##### _Note:_ +> While the `up` sub-command is provided as a convenience to quickly set up and +> install a "fresh" NixOS system on current hardware, committing these files is +> discouraged. +> +> They are placed in the git staging area automatically because they would be +> invisible to the flake otherwise, but it is best to move what you need from +> them directly into a host module of your own making, and commit that instead. +# Installation + +Once your ready to deploy `hosts/my-host.nix`: +```sh +flk my-host switch +``` + + +This calls `nixos-rebuild` with sudo to build and install your configuration. + +> ##### _Notes:_ +> - Instead of `switch`, you can pass `build`, `test`, `boot`, etc just as with +> `nixos-rebuild`. +> +> - It is convenient to have the template living at `/etc/nixos` so you can +> simply `sudo nixos-rebuild switch` from anywhere on the system, but it is +> not required. + + diff --git a/doc/start/index.md b/doc/start/index.md new file mode 100644 index 0000000..d74f726 --- /dev/null +++ b/doc/start/index.md @@ -0,0 +1,38 @@ +# Quick Start +The only dependency is nix, so make sure you have it [installed][install-nix]. + +## Get the Template +Here is a snippet that will get you the template without the git history: +```sh +nix-shell https://github.com/nrdxp/nixflk/archive/core.tar.gz -A shell \ + --run "flk get core" + +cd flk + +nix-shell + +git init +git add . +git commit -m init + +cachix use nrdxp +``` + +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. + +> ##### _Notes:_ +> - You can change `core` to [`community`](../introduction.md#community-profiles) +> in the call to `flk get` +> - Flakes ignore files that have not been added to git, so be sure to stage new +> files before building the system. + +## Next Steps: +- [Make installable ISO](./iso.md) +- [Already on NixOS](./from-nixos.md) + + +[install-nix]: https://nixos.org/manual/nix/stable/#sect-multi-user-installation diff --git a/doc/start/iso.md b/doc/start/iso.md new file mode 100644 index 0000000..aa08947 --- /dev/null +++ b/doc/start/iso.md @@ -0,0 +1,11 @@ +# ISO + +Making and writing an installable iso for `hosts/NixOS.nix` is as simple as: +```sh +flk iso NixOS + +dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \ + status=progress oflag=sync +``` + +This works for any file matching `hosts/*.nix` excluding `default.nix`. diff --git a/extern/README.md b/extern/README.md new file mode 100644 index 0000000..58f20e2 --- /dev/null +++ b/extern/README.md @@ -0,0 +1,10 @@ +# External Art +When you need to use a module, overlay, or pass a value from one of your inputs +to the rest of your NixOS configuration, [extern][extern] is where you do it. + +Modules and overlays are self explanatory, and the `specialArgs` attribute is +used to extend the arguments passed to all NixOS modules, allowing for +arbitrary values to be passed from flake inputs to the rest of your +configuration. + +[extern]: https://github.com/nrdxp/nixflk/tree/core/extern/default.nix diff --git a/extern/default.nix b/extern/default.nix index 14c3ca8..30cd189 100644 --- a/extern/default.nix +++ b/extern/default.nix @@ -12,7 +12,7 @@ # passed to all nixos modules specialArgs = { - unstableModulesPath = "${master}/nixos/modules"; + overrideModulesPath = "${override}/nixos/modules"; hardware = nixos-hardware.nixosModules; }; } diff --git a/flake.lock b/flake.lock index d4ada6f..6fa234f 100644 --- a/flake.lock +++ b/flake.lock @@ -7,7 +7,7 @@ "nixos" ], "nixos-unstable": [ - "master" + "override" ], "pre-commit-hooks-nix": "pre-commit-hooks-nix" }, @@ -93,7 +93,7 @@ "type": "github" } }, - "master": { + "override": { "locked": { "lastModified": 1612717294, "narHash": "sha256-V3j1rA4a3Lzf5pdbFHzs9jUcOKB91MFO3X8nMY+lK5c=", @@ -174,7 +174,7 @@ "devshell": "devshell", "flake-utils": "flake-utils", "home": "home", - "master": "master", + "override": "override", "nixos": "nixos", "nixos-hardware": "nixos-hardware", "nur": "nur" diff --git a/flake.nix b/flake.nix index e077d37..4a0a535 100644 --- a/flake.nix +++ b/flake.nix @@ -3,9 +3,7 @@ inputs = { - # Once desired, bump master's locked revision: - # nix flake update --update-input master - master.url = "nixpkgs/master"; + override.url = "nixpkgs/master"; nixos.url = "nixpkgs/release-20.09"; home.url = "github:nix-community/home-manager/release-20.09"; home.inputs.nixpkgs.follows = "nixos"; @@ -14,7 +12,7 @@ nixos-hardware.url = "github:nixos/nixos-hardware"; ci-agent.url = "github:hercules-ci/hercules-ci-agent"; ci-agent.inputs.nixos-20_09.follows = "nixos"; - ci-agent.inputs.nixos-unstable.follows = "master"; + ci-agent.inputs.nixos-unstable.follows = "override"; }; outputs = @@ -22,7 +20,7 @@ , ci-agent , home , nixos - , master + , override , flake-utils , nur , devshell diff --git a/hosts/README.md b/hosts/README.md new file mode 100644 index 0000000..a8f4c9d --- /dev/null +++ b/hosts/README.md @@ -0,0 +1,43 @@ +# 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, nixflk 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` 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 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. + +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). + +This is a good place to import sets of profiles, called [suites](../suites), +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. + +## Example + +`hosts/librem.nix`: +```nix +{ suites, hardware, ... }: +{ + imports = suites.laptop ++ [ hardware.purism-librem-13v3 ]; + + 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 diff --git a/hosts/default.nix b/hosts/default.nix index 525ef7e..b5e31a6 100644 --- a/hosts/default.nix +++ b/hosts/default.nix @@ -1,6 +1,6 @@ { lib , nixos -, master +, override , nixos-hardware , pkgs , self @@ -24,15 +24,15 @@ let let core = import ../profiles/core; - modOverrides = { config, unstableModulesPath, ... }: + modOverrides = { config, overrideModulesPath, ... }: let - unstable = import ../unstable; - inherit (unstable) modules disabledModules; + overrides = import ../overrides; + inherit (overrides) modules disabledModules; in { disabledModules = modules ++ disabledModules; imports = map - (path: "${unstableModulesPath}/${path}") + (path: "${overrideModulesPath}/${path}") modules; }; @@ -44,7 +44,7 @@ let networking.hostName = hostName; nix.nixPath = [ - "nixos-unstable=${master}" + "nixos-unstable=${override}" "nixos=${nixos}" "nixpkgs=${nixos}" ]; @@ -52,7 +52,6 @@ let nixpkgs = { inherit pkgs; }; nix.registry = { - master.flake = master; nixflk.flake = self; nixpkgs.flake = nixos; }; diff --git a/lib/default.nix b/lib/default.nix index 857433d..cde0042 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -83,11 +83,11 @@ in (system: let extern = import ../extern { inherit inputs; }; - unstable = pkgImport inputs.master [ ] system; - overrides = (import ../unstable).packages; + overridePkgs = pkgImport inputs.override [ ] system; + overridesOverlay = (import ../overrides).packages; overlays = [ - (overrides unstable) + (overridesOverlay overridePkgs) self.overlay (final: prev: { lib = (prev.lib or { }) // { @@ -173,7 +173,7 @@ in cachixAttrs = { inherit cachix; }; # modules - moduleList = import ../modules/list.nix; + moduleList = import ../modules/module-list.nix; modulesAttrs = pathsToImportedAttrs moduleList; in diff --git a/modules/README.md b/modules/README.md new file mode 100644 index 0000000..5da01cc --- /dev/null +++ b/modules/README.md @@ -0,0 +1,79 @@ +# Modules +The modules directory is a replica of nixpkg's NixOS [modules][nixpkgs-modules] +, and follows the same semantics. This allows for trivial upstreaming into +nixpkgs proper once your module is sufficiently stable. + +All modules linked in _module-list.nix_ are automatically exported via +`nixosModules.`, and imported into all [hosts](../hosts). + + +> ##### _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. + +## Semantics +In case you've never written a module for nixpkgs before, here is a brief +outline of the process. + +### Declaration +modules/services/service-category/my-service.nix: +```nix +{ config, lib, ... }: +let + cfg = config.services.myService; +in +{ + options.services.myService = { + enable = lib.mkEnableOption "Description of my new service."; + + # additional options ... + }; + + config = lib.mkIf cfg.enable { + # implementation ... + }; +} +``` + +### Import +modules/module-list.nix: +```nix +[ + ./services/service-category/my-service.nix +] +``` + +## Usage + +### Internal +profiles/profile-category/my-profile.nix: +```nix +{ ... }: +{ + services.MyService.enable = true; +} +``` + +### External +flake.nix: +```nix +{ + # inputs omitted + + outputs = { self, nixflk, nixpkgs, ... }: { + nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem { + system = "..."; + + modules = [ + nixflk.nixosModules.my-service + ({ ... }: { + services.MyService.enable = true; + }) + ]; + }; + }; +} +``` + +[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules diff --git a/modules/list.nix b/modules/module-list.nix similarity index 100% rename from modules/list.nix rename to modules/module-list.nix diff --git a/overlays/.gitkeep b/overlays/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/overlays/README.md b/overlays/README.md new file mode 100644 index 0000000..7d8ecdb --- /dev/null +++ b/overlays/README.md @@ -0,0 +1,25 @@ +# Overlays +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 +exported via `overlays.` _as well as_ +`packages..` (for valid systems), so all you have to do is +write it. + +## Example +overlays/kakoune.nix: +```nix +final: prev: { + kakoune = prev.kakoune.override { + configure.plugins = with final.kakounePlugins; [ + (kak-fzf.override { fzf = final.skim; }) + kak-auto-pairs + kak-buffers + kak-powerline + kak-vertical-selection + ]; + }; +} +``` diff --git a/overrides/README.md b/overrides/README.md new file mode 100644 index 0000000..ad0670b --- /dev/null +++ b/overrides/README.md @@ -0,0 +1,46 @@ +# Overrides +By default, the NixOS systems are based on the latest release. While it is +trivial to change this to nixos-unstable or any other branch of nixpkgs by +changing the flake url, sometimes all we want is a single package from another +branch. + +This is what the overrides are for. By default, they are pulled directly from +nixpkgs/master, but you can change the `override` flake input url to +nixos-unstable, or even a specific sha revision. + + +## Example + +### Packages +The override packages are defined as a regular overlay with an extra arguement +`pkgs`. This refers to the packages built from the `override` flake. + +Pulling the manix package from the override flake: +```nix +{ + packages = pkgs: final: prev: { + inherit (pkgs) manix; + }; +} +``` + +### Modules + +You can also pull modules from override. Simply specify their path relative to +the nixpkgs [modules][nixpkgs-modules] directory. The old version will be added +to `disabledModules` and the new version imported into the configuration. + +Pulling the zsh module from the override flake: +```nix +{ + modules = [ "programs/zsh/zsh.nix" ]; +} +``` + +> ##### _Note:_ +> Sometimes a modules name will change from one branch to another. This is what +> the `disabledModules` list is for. If the module name changes, the old +> version will not automatically be disabled, so simply put it's old name in +> this list to disable it. + +[nixpkgs-modules]: https://github.com/NixOS/nixpkgs/tree/master/nixos/modules diff --git a/unstable/default.nix b/overrides/default.nix similarity index 73% rename from unstable/default.nix rename to overrides/default.nix index ae7858d..c243297 100644 --- a/unstable/default.nix +++ b/overrides/default.nix @@ -1,11 +1,12 @@ +# override defaults to nixpkgs/master { - # modules to pull from master, stable version is automatically disabled + # modules to pull from override, stable version is automatically disabled modules = [ ]; - # if a modules name changed in master, add the old name here + # if a modules name changed in override, add the old name here disabledModules = [ ]; - # packages pulled from master + # packages pulled from override packages = pkgs: final: prev: { inherit (pkgs) dhall diff --git a/pkgs/README.md b/pkgs/README.md new file mode 100644 index 0000000..e84c236 --- /dev/null +++ b/pkgs/README.md @@ -0,0 +1,59 @@ +# Packages +Similar to [modules](../modules), 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. + +The only minor difference is that, instead of adding the `callPackage` call to +`all-packages.nix`, you just add it the the _default.nix_ in this directory, +which is defined as a simple overlay. + +This overlay is set as the default `overlay` output attribute for the flake. +And all the packages are exported via `packages..`, 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). + +## Example +pkgs/development/libraries/libinih/default.nix: +```nix +{ stdenv, meson, ninja, fetchFromGitHub, ... }: +let version = "r50"; +in +stdenv.mkDerivation { + pname = "libinih"; + inherit version; + + src = fetchFromGitHub { + owner = "benhoyt"; + repo = "inih"; + rev = "${version}"; + hash = "sha256-GF+TVEysaXJxSBBjMsTr2IQvRKlzdEu3rlPQ88PE3nI="; + }; + + buildInputs = [ meson ninja ]; + + mesonFlags = '' + -Ddefault_library=shared + -Ddistro_install=true + ''; + + meta = with stdenv.lib; { + description = "Simple .INI file parser in C"; + homepage = "https://github.com/benhoyt/inih"; + maintainers = [ maintainers.nrdxp ]; + license = licenses.bsd3; + platforms = platforms.all; + inherit version; + }; +} +``` + +pkgs/default.nix: +```nix +final: prev: { + libinih = prev.callPackage ./development/libraries/libinih { }; +} +``` + +[pkgs]: https://github.com/NixOS/nixpkgs/tree/master/pkgs diff --git a/profiles/README.md b/profiles/README.md new file mode 100644 index 0000000..d9c4f9f --- /dev/null +++ b/profiles/README.md @@ -0,0 +1,48 @@ +# Profiles +Profiles are simply NixOS modules which contain generic expressions suitable +for any host. A good example is the configuration for a text editor, or +window manager. If you need some concrete examples, just checkout the +community [branch](https://github.com/nrdxp/nixflk/tree/community/profiles). + +## Constraints +For the sake of consistency, there are a few minor constraints. First of all, a +profile should always be defined in a `default.nix`, and it should always be a +a function taking a single attribute set as an argument, and returning a NixOS +module which does not define any new module options. If you need to make new +module option declarations, just use [modules](../modules). + +These restrictions help simplify the import logic used to pass profles to +[suites](../suites). + +### Example +#### Correct ✔ +profiles/develop/default.nix: +```nix +{ ... }: +{ + programs.zsh.enable = true; +} +``` + +#### Incorrect ❌ +profiles/develop.nix: +```nix +{ + options = {}; +} +``` + +## Subprofiles +Profiles can also define subprofiles. They follow the same constraints outlined +above. A good top level profile should be a high level concern, such a your +personal development environment, and the subprofiles should be more concrete +program configurations such as your text editor, and shell configs. This way, +you can either pull in the whole development profile, or pick and choose +individual programs. + +## Conclusion +Profiles are the most important concept in nixflk. They allow us to keep our +nix expressions self contained and modular. This way we can maximize reuse +while minimizing boilerplate. Always strive to keep your profiles as generic +and modular as possible. Anything machine specific belongs in your +[host](../hosts) files. diff --git a/secrets/.gitattributes b/secrets/.gitattributes index 5ccf582..ff69eb2 100644 --- a/secrets/.gitattributes +++ b/secrets/.gitattributes @@ -1,2 +1,3 @@ * filter=git-crypt diff=git-crypt .gitattributes !filter !diff +README.md !filter !diff diff --git a/secrets/README.md b/secrets/README.md new file mode 100644 index 0000000..107b49f --- /dev/null +++ b/secrets/README.md @@ -0,0 +1,18 @@ +# Secrets +Secrets are managed using [git-crypt][git-crypt] so you can keep your flake in +a public repository like GitHub without exposing your password or other +sensitive data. + +By default, everything in the secrets folder is automatically encrypted. Just +be sure to run `git-crypt init` before putting anything in here. + +> ##### _Note:_ +> Currently, there is [no mechanism][secrets-issue] in nix to deploy secrets +> within the nix/store so, if they end up in the nix/store after deployment, they +> will be world readable on that machine. +> +> The author of nixflk intends to implement a workaround for this situation in +> the near future, but for the time being, simple be aware of this. + +[git-crypt]: https://github.com/AGWA/git-crypt +[secrets-issue]: https://github.com/NixOS/nix/issues/8 diff --git a/shell/default.nix b/shell/default.nix index 963be9a..caeceed 100644 --- a/shell/default.nix +++ b/shell/default.nix @@ -23,7 +23,6 @@ pkgs.devshell.mkShell { nixos-install nixos-generate-config nixos-enter - mdbook ]; env = { inherit name; }; diff --git a/suites/README.md b/suites/README.md new file mode 100644 index 0000000..e8f7489 --- /dev/null +++ b/suites/README.md @@ -0,0 +1,24 @@ +# Suites +Suites provide a mechanism for users to easily combine and name collecitons of +profiles. For good examples, check out the suites defined in the community +[branch](https://github.com/nrdxp/nixflk/blob/community/suites/default.nix). + +In the future, we will use suites as a mechanism for deploying various machine +types which don't depend on hardware, such as vm's and containers. + +## Definition +```nix +rec { + workstation = [ profiles.develop profiles.graphical users.nixos ]; + mobileWS = workstation ++ [ profiles.laptop ]; +} +``` + +## Usage +`hosts/my-laptop.nix`: +```nix +{ suites, ... }: +{ + imports = suites.mobileWS; +} +``` diff --git a/users/README.md b/users/README.md new file mode 100644 index 0000000..4963fdf --- /dev/null +++ b/users/README.md @@ -0,0 +1,51 @@ +# Users + +Users are a special case of [profiles](../profiles) 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/nrdxp/nixflk/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; + }; +} + +``` + +## External Usage +You can easily use the defined home-manager configurations outside of NixOS +using the `hmActivations` meta-package defined in the flakes `legacyPackages` +output. The [flk](../doc/flk) 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:nrdxp/nixflk#hmActivationPackages.NixOS.nixos" + +# activate +./result/activate && unlink result +``` + +[home-manager]: https://nix-community.github.io/home-manager