README: simply and update

This commit is contained in:
Timothy DeHerrera 2020-08-02 16:10:53 -06:00
parent 1870fa29bd
commit 090cc0aa32
No known key found for this signature in database
GPG Key ID: 8985725DB5B0C122
3 changed files with 94 additions and 123 deletions

32
DOC.md
View File

@ -42,30 +42,12 @@ a particular interactive user. Its primarily for declarations to
`users.users.<new-user>` where `<new-user>.isNormalUser` is true. `users.users.<new-user>` where `<new-user>.isNormalUser` is true.
This is a convenient place to import your profiles such that a particular user This is a convenient place to import your profiles such that a particular user
always has a reliable stack. 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 For convenience, [home-manager][home-manager] is available automatically for
home directory setup and should only be used from this directory. home directory setup and should only be used from this directory.
## Lib
The [lib](lib) directory contains a file `utils.nix` which is an attribute set
meant to consist mainly of utility functions you might want to write and use
throughout the configuration. They are available via a new `usr` attribute
passed to every NixOS module, eg:
```
# hosts/some-host.nix
{ usr, ... }:
let
inherit (usr) utils;
data = usr.utils.myFunction # ...
in
{
# NixOS configuration
}
```
## Secrets ## Secrets
Anything you wish to keep encrypted goes in the `secrets` directory, which is Anything you wish to keep encrypted goes in the `secrets` directory, which is
created on first entering a `nix-shell`. created on first entering a `nix-shell`.
@ -78,6 +60,16 @@ folder by default.
To keep [profiles](profiles) reusable across configurations, secrets should To keep [profiles](profiles) reusable across configurations, secrets should
only be imported from the `users` or [`hosts`](hosts) directory. only be imported from the `users` or [`hosts`](hosts) directory.
## Cachix
When using:
```
cachix use <your-cachix>
```
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.<your-cachix>`.
## Modules, Packages and Overlays ## Modules, Packages and Overlays
All expressions in both [modules/list.nix](modules/list.nix) and All expressions in both [modules/list.nix](modules/list.nix) and
[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the [pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the

173
README.md
View File

@ -1,113 +1,84 @@
# Introduction # Introduction
A NixOS configuration template using the experimental [flakes][rfc] mechanism. Herein lies a [NixOS][NixOS] configuration template using the new [flakes][wiki]
Its aim is to provide a generic repository which neatly separates concerns mechanism. Its aim is to provide a generic repository which neatly separates
and allows one to get up and running with NixOS faster than ever. concerns and allows one to get up and running with NixOS faster than ever, while
keeping your code clean and organized.
A core goal is to facilitate a (mostly) seamless transition to flakes. Some key advantages include:
You could start by simply importing your `configuration.nix` from a module * A single home for all your Nix expressions, easily sharable and portable!
in [hosts](hosts). There may be some translation if you import anything * Skip the setup, simply use the included [nix-shell](./shell.nix) or
from the `NIX_PATH`, e.g. `import <nixpkgs> {}`, but the majority of any valid [direnv][direnv] profile and get up and running with flakes right away.
NixOS config should work right out of the box. Once your up and running, you * Thanks to flakes, the entire system is more [deterministic](./flake.lock).
may wish to modify your configuration to adhere to the [ideals](DOC.md) of this * Systems defined under [hosts](./hosts) are automatically imported into
project. `nixosConfigurations`, ready to deploy.
* [Profiles](./profiles/list.nix) are a simple mechanism for using portable
code across machines, and are available to share via the
`nixosModules.profiles` output.
* Defined [packages](./pkgs/default.nix) and
[modules](./modules/list.nix), are automatically wired and available from
anywhere. They are _also_ sharable via their respective flake outputs.
* Easily [override](./pkgs/override.nix) packages from different nixpkgs versions.
* Keep [user](./users) configuration isolated and easily reusable by taking
advantage of [user profiles](./users/profiles) and [home-manager][home-manager].
* [Overlay](./overlays) files are automatically available and sharable.
For a more detailed explanation of the code structure, check out the
[docs](./DOC.md).
### ⚠ Advisory ### ⚠ Advisory
Flakes are still an experimental feature, so not everything works yet. However, Flakes are still new, so not everything works yet. However, it has been to
it has been merged upstream, and for those using cloud deployments, there is merged in [nixpkgs][nixpkgs] via [`pkgs.nixFlakes`][nixFlakes]. Thus, this
now [nixops](https://github.com/NixOS/nixops/tree/flake-support) support! project should be considered _experimental_, until flakes become the default.
Also, flakes are meant to deprecate nix-channels. I'd recommend not
installing any. If your really want them, they should work if you hook them
into your `NIX_PATH` manually.
## Flake Talk:
[![Flake talk at NixConf][thumb]][video]
Also, flakes are meant to deprecate nix-channels. It's recommend not to install
any. If your really want them, they should work if you hook them into
`NIX_PATH`.
# Setup # Setup
There are many way to get up and running. You can fork this repo or use it as
a template. There is a [bare branch][bare] if you want to start with a
completely empty template and make your own profiles from scratch.
```sh You'll need to have NixOS already installed since the `nixos-install` script
# This is not needed if your using direnv: doesn't yet support flakes.
nix-shell
# It's recommend to start a new branch: If you already have [nix-command][nix-command] setup you can:
git checkout -b $new_branch template ```
# for standard template
nix flake new -t "github:nrdxp/nixflk" flk
# Generate a hardware config: # for bare template
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix nix flake new -t "github:nrdxp/nixflk/bare" flk
# Edit the new file, removing `not-detected.nix` from the imports.
# In order to maintain purity flakes cannot resolve from the NIX_PATH.
# You could import your existing `configuration.nix`, or the generic
# `./hosts/NixOS.nix` from here. The latter sets up Network Manger,
# an efi bootloader, an empty root password, and a generic user
# named `nixos`.
# Also ensure your file systems are set the way you want:
$EDITOR ./hosts/${new_host}.nix
# Backup your existing config:
mv /etc/nixos /etc/nixos.old
# Ensure this flake can be found in its expected location:
ln -s $PWD /etc/nixos
# A flake is vcs based, so only git aware files are bundled
# adding a new file to staging is enough:
git add ./hosts/${new_host}.nix
# A generic `rebuild` wrapper for `nix build` is provided
# bypassing the need for `nixos-rebuild`.
# Usage: rebuild [host] {switch|boot|test|dry-activate}
# where `host` is any file living in the `./hosts` directory
# Test your new deployment; this will be run as root:
rebuild $new_host test
# You may wish to start by creating a user:
mkdir users/new-user && $EDITOR users/new-user/default.nix
# Once your satisfied, permanently deploy with:
rebuild $new_host switch
``` ```
Please read the [doc](DOC.md) in order to understand the impetus However you decide to acquire the repo, once you have it, you'll want to __move
behind the directory structure. or symlink__ it to `/etc/nixos` for ease of use. Once inside:
## Additional Capabilities ```
nix-shell # or `direnv allow` if you prefer
```
From here it's up to you. You can deploy the barebones [NixOS](./hosts/NixOS.nix)
host and build from there, or you can copy your existing `configuration.nix`.
You'll probably at least need to setup your `fileSystems` and make sure the
[locale](./local/locale.nix) is correct.
Once you're ready to deploy you can use `nixos-rebuild` if your NixOS version
is recent enough to support flakes, _or_ the [shell.nix](./shell.nix) defines
its own `rebuild` command in case you need it.
```
# Usage: rebuild host {switch|boot|test|iso}
rebuild <host-filename> test
```
## Build an ISO
You can make an ISO and customize it by modifying the [niximg](./hosts/niximg.nix)
file:
```sh ```sh
# Make an iso image based on `./hosts/niximg.nix`:
rebuild iso rebuild iso
# Install any package the flake exports:
nix profile install ".#packages.x86_64-linux.myPackage"
```
this flake exports multiple outputs for use in other flakes, or forks
of this one:
```nix
# external flake.nix
{
# ...
inputs.nixflk.url = "github:nrdxp/nixflk";
outputs = { self, nixpkgs, nixflk }: {
nixosConfigurations.newConfig = nixflk.nixosConfigurations.someConfig;
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{ nixpkgs.overlays = nixflk.overlays; }
nixflk.nixosModules.myModule
];
};
};
}
``` ```
### NUR usage ### NUR usage
@ -119,6 +90,9 @@ Since NUR packages are completely unchecked, they are not included by default.
Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR#nur-usage) Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR#nur-usage)
for usage. for usage.
## Flake Talk:
[![Flake talk at NixConf][thumb]][video]
# License # License
This software is licensed under the [MIT License](COPYING). This software is licensed under the [MIT License](COPYING).
@ -130,11 +104,14 @@ included here, which may be derivative works of the packages to
which they apply. The aforementioned artifacts are all covered by the which they apply. The aforementioned artifacts are all covered by the
licenses of the respective packages. licenses of the respective packages.
[bare]: https://github.com/nrdxp/nixflk/tree/bare
[direnv]: https://direnv.net [direnv]: https://direnv.net
[home-manager]: https://github.com/rycee/home-manager
[nix-command]: https://nixos.wiki/wiki/Nix_command
[nixFlakes]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/package-management/nix/default.nix#L211
[NixOS]: https://nixos.org [NixOS]: https://nixos.org
[nixpkgs]: https://github.com/NixOS/nixpkgs
[nur]: https://github.com/nix-community/NUR [nur]: https://github.com/nix-community/NUR
[old]: https://github.com/nrdxp/nixos [wiki]: https://nixos.wiki/wiki/Flakes
[pr]: https://github.com/NixOS/nixpkgs/pull/68897
[rfc]: https://github.com/tweag/rfcs/blob/flakes/rfcs/0049-flakes.md
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0
[thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg [thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0

View File

@ -1,16 +1,13 @@
{ pkgs ? import <nixpkgs> { } }: { pkgs ? import <nixpkgs> { } }:
let let
configs = "${toString ./.}#nixosConfigurations"; configs = "${toString ./.}#nixosConfigurations";
hostname = pkgs.lib.fileContents /etc/hostname;
build = "config.system.build"; build = "config.system.build";
rebuild = pkgs.writeShellScriptBin "rebuild" '' rebuild = pkgs.writeShellScriptBin "rebuild" ''
if [[ -z $1 ]]; then if [[ -z $1 ]]; then
echo "Usage: $0 [host] {switch|boot|test|iso}" echo "Usage: $(basename $0) host {switch|boot|test|iso}"
elif [[ $1 == "iso" ]]; then elif [[ $1 == "iso" ]]; then
nix build ${configs}.niximg.${build}.isoImage nix build ${configs}.niximg.${build}.isoImage
elif [[ -z $2 ]]; then
sudo -E nix shell -vv ${configs}.${hostname}.${build}.toplevel -c switch-to-configuration $1
else else
sudo -E nix shell -vv ${configs}.$1.${build}.toplevel -c switch-to-configuration $2 sudo -E nix shell -vv ${configs}.$1.${build}.toplevel -c switch-to-configuration $2
fi fi
@ -18,7 +15,12 @@ let
in in
pkgs.mkShell { pkgs.mkShell {
name = "nixflk"; name = "nixflk";
nativeBuildInputs = with pkgs; [ git git-crypt nixFlakes rebuild ]; nativeBuildInputs = with pkgs; [
git
git-crypt
nixFlakes
rebuild
];
shellHook = '' shellHook = ''
mkdir -p secrets mkdir -p secrets