dusk/ark
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

README: simply and update

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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.
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
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
Anything you wish to keep encrypted goes in the `secrets` directory, which is
created on first entering a `nix-shell`.
@ -78,6 +60,16 @@ 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 <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
All expressions in both [modules/list.nix](modules/list.nix) and
[pkgs/default.nix](pkgs/default.nix) are available globally, anywhere else in the

173
README.md
View File

@ -1,113 +1,84 @@
# Introduction
A NixOS configuration template using the experimental [flakes][rfc] mechanism.
Its aim is to provide a generic repository which neatly separates concerns
and allows one to get up and running with NixOS faster than ever.
Herein lies a [NixOS][NixOS] configuration template using the new [flakes][wiki]
mechanism. Its aim is to provide a generic repository which neatly separates
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.
You could start by simply importing your `configuration.nix` from a module
in [hosts](hosts). There may be some translation if you import anything
from the `NIX_PATH`, e.g. `import <nixpkgs> {}`, but the majority of any valid
NixOS config should work right out of the box. Once your up and running, you
may wish to modify your configuration to adhere to the [ideals](DOC.md) of this
project.
Some key advantages include:
* A single home for all your Nix expressions, easily sharable and portable!
* Skip the setup, simply use the included [nix-shell](./shell.nix) or
[direnv][direnv] profile and get up and running with flakes right away.
* Thanks to flakes, the entire system is more [deterministic](./flake.lock).
* Systems defined under [hosts](./hosts) are automatically imported into
`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
Flakes are still an experimental feature, so not everything works yet. However,
it has been merged upstream, and for those using cloud deployments, there is
now [nixops](https://github.com/NixOS/nixops/tree/flake-support) support!
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]
Flakes are still new, so not everything works yet. However, it has been to
merged in [nixpkgs][nixpkgs] via [`pkgs.nixFlakes`][nixFlakes]. Thus, this
project should be considered _experimental_, until flakes become the default.
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
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
# This is not needed if your using direnv:
nix-shell
You'll need to have NixOS already installed since the `nixos-install` script
doesn't yet support flakes.
# It's recommend to start a new branch:
git checkout -b $new_branch template
If you already have [nix-command][nix-command] setup you can:
```
# for standard template
nix flake new -t "github:nrdxp/nixflk" flk
# Generate a hardware config:
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
# 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
# for bare template
nix flake new -t "github:nrdxp/nixflk/bare" flk
```
Please read the [doc](DOC.md) in order to understand the impetus
behind the directory structure.
However you decide to acquire the repo, once you have it, you'll want to __move
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
# Make an iso image based on `./hosts/niximg.nix`:
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
@ -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)
for usage.
## Flake Talk:
[![Flake talk at NixConf][thumb]][video]
# License
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
licenses of the respective packages.
[bare]: https://github.com/nrdxp/nixflk/tree/bare
[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
[nixpkgs]: https://github.com/NixOS/nixpkgs
[nur]: https://github.com/nix-community/NUR
[old]: https://github.com/nrdxp/nixos
[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
[wiki]: https://nixos.wiki/wiki/Flakes
[thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg
[video]: https://www.youtube.com/watch?v=UeBX7Ide5a0

12
shell.nix
View File

@ -1,16 +1,13 @@
{ pkgs ? import <nixpkgs> { } }:
let
configs = "${toString ./.}#nixosConfigurations";
hostname = pkgs.lib.fileContents /etc/hostname;
build = "config.system.build";
rebuild = pkgs.writeShellScriptBin "rebuild" ''
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
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
sudo -E nix shell -vv ${configs}.$1.${build}.toplevel -c switch-to-configuration $2
fi
@ -18,7 +15,12 @@ let
in
pkgs.mkShell {
name = "nixflk";
nativeBuildInputs = with pkgs; [ git git-crypt nixFlakes rebuild ];
nativeBuildInputs = with pkgs; [
git
git-crypt
nixFlakes
rebuild
];
shellHook = ''
mkdir -p secrets