ark/README.md

135 lines
4.2 KiB
Markdown
Raw Normal View History

2019-12-03 08:18:30 +03:00
# Introduction
2020-01-05 13:43:28 +03:00
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.
2020-01-12 05:51:23 +03:00
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.
### ⚠ Advisory
2020-07-09 09:23:54 +03:00
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!
2019-12-05 11:36:15 +03:00
2020-01-12 05:51:23 +03:00
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]
2019-12-05 11:36:15 +03:00
# Setup
2020-01-05 13:43:28 +03:00
```sh
2020-01-12 05:51:23 +03:00
# This is not needed if your using direnv:
2020-01-05 13:43:28 +03:00
nix-shell
2020-01-12 05:51:23 +03:00
# It's recommend to start a new branch:
2020-01-05 13:43:28 +03:00
git checkout -b $new_branch template
2020-01-12 05:51:23 +03:00
# Generate a hardware config:
2020-01-05 13:43:28 +03:00
nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
2020-01-07 23:57:55 +03:00
# Edit the new file, removing `not-detected.nix` from the imports.
# In order to maintain purity flakes cannot resolve from the NIX_PATH.
2020-01-12 05:51:23 +03:00
# 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
2020-01-12 05:51:23 +03:00
# Backup your existing config:
mv /etc/nixos /etc/nixos.old
2020-01-12 05:51:23 +03:00
# Ensure this flake can be found in its expected location:
ln -s $PWD /etc/nixos
2020-01-12 05:51:23 +03:00
# 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
# Test your new deployment:
sudo nixos-rebuild $new_host test
2020-01-12 05:51:23 +03:00
# You may wish to start by creating a user:
mkdir users/new-user && $EDITOR users/new-user/default.nix
2019-12-05 11:36:15 +03:00
2020-01-12 05:51:23 +03:00
# Once your satisfied, permanently deploy with:
sudo nixos-rebuild $new_host switch
2020-01-12 05:51:23 +03:00
```
2019-12-05 11:36:15 +03:00
2020-01-12 05:51:23 +03:00
Please read the [doc](DOC.md) in order to understand the impetus
behind the directory structure.
## Additional Capabilities
2020-01-05 13:43:28 +03:00
```sh
2020-01-12 05:51:23 +03:00
# Make an iso image based on `./hosts/niximg.nix`:
build-iso
2019-12-05 11:36:15 +03:00
2020-01-12 05:51:23 +03:00
# Install any package the flake exports:
2020-01-05 13:43:28 +03:00
nix profile install ".#packages.x86_64-linux.myPackage"
2019-12-05 11:36:15 +03:00
```
this flake exports multiple outputs for use in other flakes, or forks
of this one:
2020-01-05 13:43:28 +03:00
```nix
# external flake.nix
{
# ...
inputs.nixflk.url = "github:nrdxp/nixflk";
outputs = { self, nixpkgs, nixflk }: {
2020-01-06 04:26:09 +03:00
nixosConfigurations.newConfig = nixflk.nixosConfigurations.someConfig;
2020-01-05 13:43:28 +03:00
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{ nixpkgs.overlays = nixflk.overlays; }
nixflk.nixosModules.myModule
];
};
};
}
2020-01-05 13:43:28 +03:00
```
### NUR usage
You can use packages, modules and overlays from the
[Nix User Repository][nur].
Since NUR packages are completely unchecked, they are not included by default.
2020-01-11 10:29:16 +03:00
Check out the NUR [branch](https://github.com/nrdxp/nixflk/tree/NUR#nur-usage)
for usage.
2020-01-06 10:16:21 +03:00
2019-12-03 08:18:30 +03:00
# License
This software is licensed under the [MIT License](COPYING).
Note: MIT license does not apply to the packages built by this configuration,
merely to the files in this repository (the Nix expressions, build
scripts, NixOS modules, etc.). It also might not apply to patches
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.
[direnv]: https://direnv.net
2019-12-03 08:18:30 +03:00
[NixOS]: https://nixos.org
[nur]: https://github.com/nix-community/NUR
2019-12-03 08:18:30 +03:00
[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
[thumb]: https://img.youtube.com/vi/UeBX7Ide5a0/hqdefault.jpg