⚠ Advisory ⚠
DevOS requires the flakes feature available via an experimental branch of nix. Until nix 2.4 is released, this project should be considered unstable.
Why?
Make an awesome template for NixOS users, with consideration for common tools like home-manager, devshell, and more.
No. Why flakes?
Flakes are a part of an explicit push to improve Nix's UI, and have become an intergral part of that effort.
They also make Nix expressions easier to distribute and reuse with convient flake references for building or using packages, modules, and whole systems.
Getting Started
Check out the guide to get up and running.
Also, have a look at flake.nix. If anything is not immediately
discoverable via "digga
's mkFlake
,
please file a bug report.
Status: Beta
Although this project has already matured quite a bit, especially through
recent outfactoring of digga
, a fair amount of api polishing is still
expected. There are unstable versions (0.x.x) to help users keep track
of changes and progress, and a develop
branch for the brave 😜
In the Wild
- The original authors
Shoulders
This work does not reinvent the wheel. It stands on the shoulders of the following giants:
:onion: — like the layers of an onion
:family: — like family
:heart:
Inspiration & Art
Divnix
The divnix org is an open space that spontaniously formed out of "the Nix". It is really just a place where otherwise unrelated people a) get together and b) stuff done.
It's a place to stop "geeking out in isolation" (or within company boundaries), experiment and learn together and iterate quickly on best practices. That's what it is.
It might eventually become a non-profit if that's not too complicated or if those goals are sufficiently upstreamed into "the Nix", dissolved.
License
DevOS is licensed under the MIT License.
Quick Start
The only dependency is nix, so make sure you have it installed.
Get the Template
Here is a snippet that will get you the template without the git history:
nix-shell -p cachix --run "cachix use nrdxp"
nix-shell https://github.com/divnix/devos/archive/core.tar.gz -A shell \
--run "flk get core"
cd flk
nix-shell
git init
git add .
git commit -m init
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 is added for faster deployment.
Notes:
- Flakes ignore files that have not been added to git, so be sure to stage new files before building the system.
- You can choose to simply clone the repo with git if you want to follow upstream changes.
- If the
nix-shell -p cachix --run "cachix use nrdxp"
line doesn't work you can try with sudo:sudo nix-shell -p cachix --run "cachix use nrdxp"
Next Steps:
ISO
Making and writing an installable iso for hosts/NixOS.nix
is as simple as:
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
.
ISO image nix store & cache
The iso image holds the store to the live environment and also acts as a binary cache
to the installer. To considerably speed up things, the image already includes all flake
inputs
as well as the devshell
closures.
While you could provision any machine with a single stick, a custom-made iso for the host you want to install DevOS to, maximises those local cache hits.
For hosts that don't differ too much, a single usb stick might be ok, whereas when there are bigger differences, a custom-made usb stick will be considerably faster.
Bootstrapping
This will help you boostrap a bare host with the help of the bespoke iso live installer.
Note: nothing prevents you from remotely executing the boostrapping process. See below.
Once your target host has booted into the live iso, you need to partion and format your disk according to the official manual.
Mount partitions
Then properly mount the formatted partitions at /mnt
, so that you can
install your system to those new partitions.
Mount nixos
partition to /mnt
and — for UEFI — boot
partition to /mnt/boot
:
$ mount /dev/disk/by-label/nixos /mnt
$ mkdir -p /mnt/boot && mount /dev/disk/by-label/boot /mnt/boot # UEFI only
$ swapon /dev/$your_swap_partition
Install
Install using the flk
wrapper baked into the iso off of a copy of devos
from the time the iso was built:
$ cd /iso/devos
$ nix develop
$ flk install NixOS --impure # use same host as above
Notes of interest
Remote access to the live installer
The iso live installer comes preconfigured with a network configuration
which announces it's hostname via MulticastDNS as hostname.local
,
that is NixOS.local
in the iso example.
In the rare case that MulticastDNS is not availabe or turned off
in your network, there is a static link-local IPv6 address configured to
fe80::47
(mnemonic from the letter's position in the english alphabet:
n=14 i=9 x=24; 47 = n+i+x
).
Provided that you have added your public key to the authorized keys of the
root
user (hint: deploy-rs
needs passwordless
sudo access):
{ ... }:
{
users.users.root.openssh.authorizedKeys.keyFiles = [
../secrets/path/to/key.pub
];
}
You can then ssh into the live installer through one of the following options:
ssh root@NixOS.local
ssh root@fe80::47%eno1 # where eno1 is your network interface on which you are linked to the target
Note: the static link-local IPv6 address and MulticastDNS is only configured on the live installer. If you wish to enable MulticastDNS for your environment, you ought to configure that in a regular profile.
EUI-64 LLA & Host Identity
The iso's IPv6 Link Local Address (LLA) is configured with a static 64-bit Extended Unique Identifiers (EUI-64) that is derived from the host interface's Message Authentication Code (MAC) address.
After a little while (a few seconds), you can remotely discover this unique and host specific address over NDP for example with:
ip -6 neigh show # also shows fe80::47
This LLA is stable for the host, unless you need to swap that particular network card. Under this reservation, though, you may use this EUI-64 to wire up a specific (cryptographic) host identity.
From NixOS
Generate Configuration
Assuming you're happy with your existing partition layout, you can generate a basic NixOS configuration for your system using:
flk up
This will make a new file hosts/up-$(hostname).nix
, which you can edit to
your liking.
You must then add a host to nixos.hosts
in flake.nix:
{
nixos.hosts = {
modules = hosts/NixOS.nix;
};
}
Make sure your i18n.defaultLocale
and time.timeZone
are set properly for
your region. Keep in mind that networking.hostName
will be automatically
set to the name of your host;
Now might be a good time to read the docs on suites and 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 you're ready to deploy hosts/my-host.nix
:
flk my-host switch
This calls nixos-rebuild
with sudo to build and install your configuration.
Notes:
Instead of
switch
, you can passbuild
,test
,boot
, etc just as withnixos-rebuild
.It is convenient to have the template living at
/etc/nixos
so you can simplysudo nixos-rebuild switch
from anywhere on the system, but it is not required.
Key Concepts
There are few idioms unique to DevOS. This section is dedicated to helping you understand them.
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, you can make use of a couple arguments.
It is encouraged to add external art directly in your flake.nix
so the file
represents a complete dependency overview of your flake.
Overlays
External overlays can directly be added to a channel's overlays
list.
flake.nix:
{
channels.nixos.overlays = [ inputs.agenix.overlay ];
}
Upon exporting overlays, these overlays will be automatically filtered out by inspecting the inputs
argument.
Modules
There is a dedicated nixos.hostDefaults.externalModules
argument for external
modules.
flake.nix:
{
nixos.hostDefaults.externalModules = [ inputs.agenix.nixosModules.age ];
}
Home Manager
Since there isn't a hosts
concept for home-manager, externalModules is just a
top-level argument in the home
namespace.
flake.nix:
{
home.externalModules = [ doom-emacs = doom-emacs.hmModule ];
}
Note:
To avoid declaring "external" modules separately, which is obvious since they come from
inputs
, the optimal solution would be to automatically export modules that were created in your flake. But this is not possible due to NixOS/nix#4740.
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, devos 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
or hosts/system/default.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 folder name or 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.
You can set channels, systems, and add extra modules to each host by editing the
nixos.hosts
argument in flake.nix. This is the perfect place to import
host specific modules from external sources, such as the
nixos-hardware repository.
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.
This is a good place to import sets of profiles, called suites, that you intend to use on your machine.
Example
flake.nix:
{
nixos = {
imports = [ (devos.lib.importHosts ./hosts) ];
hosts = {
librem = {
channelName = "latest";
modules = [ nixos-hardware.nixosModules.purism-librem-13v3 ];
};
};
};
}
hosts/librem.nix:
{ suites, ... }:
{
imports = suites.laptop;
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
}
Overrides
Each NixOS host follows one channel. But many times it is useful to get packages or modules from different channels.
Packages
You can make use of overlays/overrides.nix
to override specific packages in the
default channel to be pulled from other channels. That file is simply an example
of how any overlay can get channels
as their first argument.
You can add overlays to any channel to override packages from other channels.
Pulling the manix package from the latest
channel:
channels: final: prev: {
__dontExport = true;
inherit (pkgs.latest) manix;
}
It is recommended to set the __dontExport
property for override specific
overlays. overlays/overrides.nix
is the best place to consolidate all package
overrides and the property is already set for you.
Modules
You can also pull modules from other channels. All modules have access to the
modulesPath
for each channel as <channelName>ModulesPath
. And you can use
disabledModules
to remove modules from the current channel.
To pull zsh module from the latest
channel this code can be placed in any module, whether its your host file, a profile, or a module in ./modules etc:
{ latestModulesPath }:
{
imports = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
disabledModules = [ "programs/zsh/zsh.nix" ];
}
Note:
Sometimes a modules name will change from one branch to another.
Profiles
Profiles are a convenient shorthand for the definition of options in contrast to their declaration. They're built into the NixOS module system for a reason: to elegantly provide a clear separation of concerns.
Creation
Profiles are created with the rakeLeaves
function which recursively collects
.nix
files from within a folder. The recursion stops at folders with a default.nix
in them. You end up with an attribute set with leaves(paths to profiles) or
nodes(attrsets leading to more nodes or leaves).
A profile is used for quick modularization of interelated bits.
Notes:
Nested profiles
Profiles can be nested in attribute sets due to the recursive nature of rakeLeaves
.
This can be useful to have a set of profiles created for a specific purpose. It is
sometimes useful to have a common
profile that has high level concerns related
to all its sister profiles.
Example
profiles/develop/common.nix:
{
imports = [ ./zsh ];
# some generic development concerns ...
}
profiles/develop/zsh.nix:
{ ... }:
{
programs.zsh.enable = true;
# zsh specific options ...
}
The examples above will end up with a profiles set like this:
{
develop = {
common = ./profiles/develop/common.nix;
zsh = ./profiles/develop/zsh.nix;
};
}
Conclusion
Profiles are the most important concept in DevOS. They allow us to keep our Nix expressions self contained and modular. This way we can maximize reuse across hosts while minimizing boilerplate. Remember, anything machine specific belongs in your host files instead.
Suites
Suites provide a mechanism for users to easily combine and name collecitons of profiles.
suites
are defined in the importables
argument in either the home
or nixos
namespace. They are a special case of an importable
which get passed as a special
argument (one that can be use in an imports
line) to your hosts. All lists defined
in suites
are flattened and type-checked as paths.
Definition
rec {
workstation = [ profiles.develop profiles.graphical users.nixos ];
mobileWS = workstation ++ [ profiles.laptop ];
}
Usage
hosts/my-laptop.nix
:
{ suites, ... }:
{
imports = suites.mobileWS;
}
Users
Users are a special case of profiles that define system users and 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.
Basic Usage
users/myuser/default.nix
:
{ ... }:
{
users.users.myuser = {
isNormalUser = true;
};
home-manager.users.myuser = {
programs.mpv.enable = true;
};
}
Home Manager
Home Manager support follows the same principles as regular nixos configurations,
it even gets its own namespace in your flake.nix
as home
.
All modules defined in user modules will be imported to
Home Manager.
User profiles can be collected in a similar fashion as system ones into a suites
argument that gets passed to your home-manager users.
Example
{
home-manager.users.nixos = { suites, ... }: {
imports = suites.base;
};
}
External Usage
You can easily use the defined home-manager configurations outside of NixOS
using the homeConfigurations
flake output. The 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:
# 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:
# build
nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPackage"
# activate
./result/activate && unlink result
Layout
Each of the following sections is a directory whose contents are output to the outside world via the flake's outputs. Check each chapter for details.
Modules
The modules directory is a replica of nixpkg's NixOS 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.<file-basename>
, and imported into all 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 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:
{ 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:
[
./services/service-category/my-service.nix
]
Usage
Internal
profiles/profile-category/my-profile.nix:
{ ... }:
{
services.MyService.enable = true;
}
External
flake.nix:
{
# inputs omitted
outputs = { self, devos, nixpkgs, ... }: {
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "...";
modules = [
devos.nixosModules.my-service
({ ... }: {
services.MyService.enable = true;
})
];
};
};
}
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, and
exported via overlays.<channel>/<pkgName>
as well as
packages.<system>.<pkgName>
(for valid systems), so all you have to do is
write it.
Example
overlays/kakoune.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
];
};
}
Packages
Similar to modules, the pkgs directory mirrors the upstream nixpkgs/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.
All the packages are exported via packages.<system>.<pkg-name>
, 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.
Automatic Source Updates
There is the added, but optional, convenience of declaring your sources in
pkgs/flake.nix as an input. You can then access them from the srcs
package.
This allows updates to be managed automatically by simply
updating the lock file. No
more manually entering sha256 hashes!
As an added bonus, version strings are also generated automatically from either the flake ref, or the date and git revision of the source.
Example
pkgs/development/libraries/libinih/default.nix:
{ stdenv, meson, ninja, lib, srcs, ... }:
let inherit (srcs) libinih; in
stdenv.mkDerivation {
pname = "libinih";
# version will resolve to 53, as specified in the final example below
inherit (libinih) version;
src = libinih;
buildInputs = [ meson ninja ];
# ...
}
pkgs/default.nix:
final: prev: {
libinih = prev.callPackage ./development/libraries/libinih { };
}
pkgs/flake.nix:
{
description = "Package sources";
inputs = {
libinih.url = "github:benhoyt/inih/r53";
libinih.flake = false;
};
}
Lib
Secrets
Secrets are managed using git-crypt and agenix 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.
Agenix
Currently, there is no mechanism in nix itself to deploy secrets within the nix store because it is world-readable.
Most NixOS modules have the ability to set options to files in the system, outside the nix store, that contain sensitive information. You can use agenix to easily setup those secret files declaratively.
agenix encrypts secrets and stores them as .age files in your repository.
Age files are encrypted with multiple ssh public keys, so any host or user with a
matching ssh private key can read the data. The age module will add those
encrypted files to the nix store and decrypt them on activation to /run/secrets
.
Setup
All hosts must have openssh enabled, this is done by default in the core profile.
You need to populate your secrets/secrets.nix
with the proper ssh public keys.
Be extra careful to make sure you only add public keys, you should never share a
private key!!
secrets/secrets.nix:
let
system = "<system ssh key>";
user = "<user ssh key>";
allKeys = [ system user ];
in
On most systems, you can get your systems ssh public key from /etc/ssh/ssh_host_ed25519_key.pub
. If
this file doesn't exist you likely need to enable openssh and rebuild your system.
Your users ssh public key is probably stored in ~/.ssh/id_ed25519.pub
or
~/.ssh/id_rsa.pub
. If you haven't generated a ssh key yet, be sure do so:
ssh-keygen -t ed25519
Note:
The underlying tool used by agenix, rage, doesn't work well with password protected ssh keys. So if you have lots of secrets you might have to type in your password many times.
Secrets
You will need the agenix
command to create secrets. DevOS conveniently provides that
in the devShell, so just run nix develop
whenever you want to edit secrets. Make sure
to always run agenix
while in the secrets/
folder, so it can pick up your secrets.nix
.
To create secrets, simply add lines to your secrets/secrets.nix
:
let
...
allKeys = [ system user ];
in
{
"secret.age".publicKeys = allKeys;
}
That would tell agenix to create a secret.age
file that is encrypted with the system
and user
ssh public key.
Then go into the secrets
folder and run:
agenix -e secret.age
This will create the secret.age
, if it doesn't already exist, and allow you to edit it.
If you ever change the publicKeys
entry of any secret make sure to rekey the secrets:
agenix --rekey
Usage
Once you have your secret file encrypted and ready to use, you can utilize the age module
to ensure that your secrets end up in /run/secrets
.
In any profile that uses a NixOS module that requires a secret you can enable a particular secret like so:
{ self, ... }:
{
age.secrets.mysecret.file = "${self}/secrets/mysecret.age";
}
Then you can just pass the path /run/secrets/mysecret
to the module.
You can make use of the many options provided by the age module to customize where and how secrets get decrypted. You can learn about them by looking at the age module.
Note:
You can take a look at the agenix repository for more information about the tool.
Testing
Testing is always an important aspect of any software development project, and NixOS offers some incredibly powerful tools to write tests for your configuration, and, optionally, run them in CI.
Unit Tests
Unit tests can be created from regular derivations, and they can do almost anything you can imagine. By convention, it is best to test your packages during their check phase. All packages and their tests will be built during CI.
Integration Tests
All your profiles defined in suites will be tested in a NixOS VM.
You can write integration tests for one or more NixOS VMs that can, optionally, be networked together, and yes, it's as awesome as it sounds!
Be sure to use the mkTest
function from digga, digga.lib.pkgs-lib.mkTest
which wraps the official testing-python function to ensure
that the system is setup exactly as it is for a bare DevOS system. There are
already great resources for learning how to use these tests effectively,
including the official docs, a fantastic blog post,
and the examples in nixpkgs.
flk command
The devshell for the project incudes a convenient script for managing your
system called flk
. Each of the following chapters is a reference for one of
its subcommands.
Rebuild
Without any of the subcommands, flk
acts as a convenient shortcut for
nixos-rebuild
:
flk NixOS build
Will build hosts/NixOS.nix. You can change out build
for switch
, test
,
etc. Any additional arguments are passed through to the call to
nixos-rebuild
.
Usage
flk help
up
The up
subcommand is a simple shortcut for nixos-generate-config
that is
compatible with devos. There is a short explanation in the the getting started
guide.
update
The update
subcommand is a simple alias for:
nix flake update
As it sounds, this will update your lock file.
Updating Package Sources
If you pass directory name then it will update that input if the directory contains a flake.nix, with an optional arguement to update only a specific input in the subflake.
For example, you can update any package sources you may have declared in pkgs/flake.nix:
flk update pkgs
or just its nixpkgs:
flk update pkgs nixpkgs
get
The get
subcommand is useful for getting a bare copy of devos without the
git history.
Usage
flk get DEST-DIR
If DEST-DIR is ommitted, it defaults to ./devos.
DigitalOcean
Now you can create a droplet using your custom image.
Making a DigitalOcean compatible image for hosts/NixOS.nix
is as simple as:
flk doi NixOS
This works for any file matching hosts/*.nix
excluding default.nix
.
ISO
Making and writing an installable iso for hosts/NixOS.nix
is as simple as:
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
.
ISO image nix store & cache
The iso image holds the store to the live environment and also acts as a binary cache
to the installer. To considerably speed up things, the image already includes all flake
inputs
as well as the devshell
closures.
While you could provision any machine with a single stick, a custom-made iso for the host you want to install DevOS to, maximises those local cache hits.
For hosts that don't differ too much, a single usb stick might be ok, whereas when there are bigger differences, a custom-made usb stick will be considerably faster.
install
The install
subcommand is a simple convenience for nixos-install
, similar
to the shortcut for nixos-rebuild
, all additional arguments are passed
through.
Example
flk install NixOS
This will install hosts/NixOS.nix to /mnt. You can override this directory
using standard nixos-install
args.
home
The home
subcommand is for using your home-manager configurations outside of
NixOS, providing an awesome mechanism for keeping your environments
synchronized, even when using other systems.
Usage
The users page contains a good usage example.
Integrations
This section explores some of the optional tools included with devos to provide a solution to common concerns such as ci and remote deployment. An effort is made to choose tools that treat nix, and where possible flakes, as first class citizens.
Cachix
The system will automatically pull a cachix.nix at the root if one exists.
This is usually created automatically by a sudo cachix use
. If you're more
inclined to keep the root clean, you can drop any generated files in the
cachix
directory into the profiles/cachix
directory without further
modification.
For example, to add your own cache, assuming the template lives in /etc/nixos,
by simply running sudo cachix use yourcache
. Then, optionally, move
cachix/yourcache.nix
to profiles/cachix/yourcache.nix
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.
deploy-rs
Deploy-rs is a tool for managing NixOS remote machines. It was chosen for devos after the author experienced some frustrations with the stateful nature of nixops' db. It was also designed from scratch to support flake based deployments, and so is an excellent tool for the job.
By default, all the hosts are also available as deploy-rs nodes,
configured with the hostname set to networking.hostName
; overridable via
the command line.
Usage
Just add your ssh key to the host:
{ ... }:
{
users.users.${sshUser}.openssh.authorizedKeys.keyFiles = [
../secrets/path/to/key.pub
];
}
And the private key to your user:
{ ... }:
{
home-manager.users.${sshUser}.programs.ssh = {
enable = true;
matchBlocks = {
${host} = {
host = hostName;
identityFile = ../secrets/path/to/key;
extraOptions = { AddKeysToAgent = "yes"; };
};
};
}
}
And run the deployment:
deploy "flk#hostName" --hostname host.example.com
Note:
Your user will need passwordless sudo access
Hercules CI
If you start adding your own packages and configurations, you'll probably have at least a few binary artifacts. With hercules we can build every package in our configuration automatically, on every commit. Additionally, we can have it upload all our build artifacts to a binary cache like cachix.
This will work whether your copy is a fork, or a bare template, as long as your repo is hosted on GitHub.
Setup
Just head over to hercules-ci.com to make an account.
Then follow the docs to set up an agent, if you want to deploy to a binary cache (and of course you do), be sure not to skip the binary-caches.json.
Ready to Use
The repo is already set up with the proper default.nix file, building all declared packages, checks, profiles and shells. So you can see if something breaks, and never build the same package twice!
If you want to get fancy, you could even have hercules deploy your configuration!
Note:
Hercules doesn't have access to anything encrypted in the secrets folder, so none of your secrets will accidentally get pushed to a cache by mistake.
You could pull all your secrets via your user, and then exclude it from allUsers to keep checks passing.
Pull Requests
All development is done in the develop
branch. Only minor bug-fixes and release
PRs should target master
.
If making a change to the template, or adding a feature, please be sure to update the relevant docs. Each directory contains its own README.md, which will automatically be pulled into the mdbook. The book is rendered on every change, so the docs should always be up to date.
We also use BORS to ensure that all pull requests pass the test suite once at least one review is completed.
Style
If you wish to contribute please follow these guidelines:
-
format your code with
nixpkgs-fmt
. The default devshell includes a pre-commit hook that does this for you. -
The commit message follows the same semantics as nixpkgs.
- You can use a
#
symbol to specify ambiguities. For example,develop#zsh: <rest of commit message>
would tell me that you're updating thezsh
subprofile living under thedevelop
profile.
- You can use a