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

README.md: be more concise

Browse Source
This commit is contained in:
Timothy DeHerrera 2020-01-05 03:43:28 -07:00
parent 6a6efbdda0
commit e7153d31fe
No known key found for this signature in database
GPG Key ID: 8985725DB5B0C122
1 changed files with 59 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
README.md
View File

@ -1,104 +1,99 @@
# Introduction # Introduction
A NixOS configuration template using the experimental [flakes][rfc] mechanism.
This project is under construction as a rewrite of my [legacy][old] Its aim is to provide a generic repository which neatly separates concerns
NixOS configuration using the experimental [flakes][rfc] mechanism. Its aim is and allows one to get up and running with NixOS faster than ever.
to provide a generic template repository which neatly separates concerns and
allows one to get up and running with NixOS faster than ever.
Flakes are still an experimental feature, but once they finally get merged Flakes are still an experimental feature, but once they finally get merged
even more will become possible, including [nixops](https://nixos.org/nixops) even more will become possible, i.e. [nixops](https://nixos.org/nixops)
support. support.
#### [Flake Talk][video] #### [Flake Talk][video]
# Usage # Usage
Enter a nix-shell either manually or automatically using [direnv][direnv]. This ```sh
will set up the experimental nix features that need to be available to use # not needed if using direnv
[flakes][pr]. nix-shell
Start a new branch based on the template branch: git checkout -b $new_branch template
```
git checkout -b <new_branch> template
```
You may want to use a generated hardware config for your machine: # generate hardware config
``` nixos-generate-config --show-hardware-config > ./hosts/${new_host}.nix
nixos-generate-config --show-hardware-config > ./hosts/<new_host>.nix
```
A basic `rebuild` command is included in the shell to replace # wrapper for `nix build` bypassing `nixos-rebuild`
`nixos-rebuild` for now: # Usage: rebuild [([host] {switch|boot|test|dry-activate})|iso]
# You can specify any of the host configurations living in the ./hosts
# directory. If omitted, it will default to your systems current hostname.
rebuild $new_host switch
``` ```
Usage: rebuild [host] {switch|boot|test}
#example using above generated config
rebuild <new_host> switch
```
You can specify one of the host configurations from the [hosts](hosts)
directory. If omitted, it will default to your systems current hostname.
And now you should be ready to start writing your nix configuration or import And now you should be ready to start writing your nix configuration or import
some of the already existing profiles. Review [contributing](#contributing) your current one. Review [structure](#structure) below on how to build your
below on how to structure your expressions. And be sure to update the layout. And be sure to update the [locale.nix](local/locale.nix) for your
[locale.nix](local/locale.nix) for your region. region.
You can always checkout my personal branch You can always checkout my personal branch
[`nrdxp`](https://github.com/nrdxp/nixflk/tree/nrdxp), for concrete examples. [`nrdxp`](https://github.com/nrdxp/nixflk/tree/nrdxp) for more concrete examples.
## Additional Capabilities ## Additional Capabilities
Making iso images: ```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"
``` ```
Will make a minimal and bootable iso image of the [niximg](hosts/niximg.nix) this flake exports overlays and modules as well:
configuration. You can customize the image by editing this file. ```nix
# external flake.nix
{
# ...
inputs.nixflk.url = "github:nrdxp/nixflk";
outputs = { self, nixpkgs, nixflk }: {
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{ nixpkgs.overlays = nixflk.overlays; }
nixflk.nixosModules.myModule
];
};
};
}
You can also install the packages declared in [pkgs](pkgs) without needing
to install NixOS. For example:
```
# from top-level
nix profile install ".#packages.x86_64-linux.purs"
``` ```
A similar mechanism exists to import the modules and overlays declared in the # Structure
flake to allow for seamless sharing between configurations.
# Structure and Layout The structure is here to keep things simple and clean. Anything sufficiently
generic can ultimately be exported for use in other flakes without getting
The purpose of this repository is to provide a standardized template structure tied up in user concerns. An additional bonus of is the ability to trivially
for NixOS machine expressions, thus enabling simpler sharing and reuse of nix swap or combine [profiles](#profiles).
expressions.
Say your friend and you are using this repository, each with your own unique
nix expressions. By simply importing your friends flake from `flake.nix` as an
input, you can have access to all of the packages, modules, overlays, and even
entire system configurations your friend has defined!
## Hosts ## Hosts
Distributions for particular machines should be stored in the [hosts](hosts) Distributions for particular machines should be stored in the [hosts](hosts)
directory. Every file in this directory will be added automatically to the directory. Every file in this directory will be added automatically to the
the `nixosConfigurations` flake output. See the the `nixosConfigurations` flake output and thus deployable. See the
[`default.nix`](hosts/default.nix) for the implementation details. [`default.nix`](hosts/default.nix) for the implementation details.
## Profiles ## Profiles
More abstract configurations suitable for reuse by multiple machines should More abstract expressions suitable for reuse by deployments should live in the
go in the [profiles](profiles) directory. A distinction is made between a module [profiles](profiles) directory. A distinction is made between a module and
and profile, in that a profile is simply a regular NixOS module, without any new profile, in that a profile is simply a regular NixOS module, without any _new_
option declarations. If you want to declare new option declarations.
[options](https://nixos.org/nixos/manual/options.html), create an expression
under the [modules](modules) directory instead.
Every profile should have a `default.nix` to easily import it. You can also Every directory here is a profile and should have a `default.nix` to import it.
stick things in the profile's subdirectory which are not automatically Profiles can have subprofiles which are just subdirectories with a `default.nix`.
imported, but are meant to be manually imported from a host (useful for less There's no hard rule that everything in the folder must be imported by its
common, or specialized configurations). `default.nix` so you can also store relevant configurations that may not be used
as often and just import them directly from a [host](#hosts) when needed.
Importantly, every subdirectory in a profile should be independently importable. Importantly, every subdirectory in a profile should be independently importable.
For example, a zsh directory lives under [profiles/develop](profiles/develop/zsh). For example, a zsh directory lives under [profiles/develop](profiles/develop/zsh).