divnix/digga
1
1
Fork 0
mirror of https://github.com/divnix/digga.git synced 2024-12-22 23:51:39 +03:00
Code Issues Projects Releases Wiki Activity
gh-pages
digga/print.html
blaggacao 4551163a83 deploy: 117be8023d
2024-05-17 10:20:03 +00:00

1324 lines
73 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="light" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Digga Library Docs</title>
<meta name="robots" content="noindex">
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="sidebar-visible no-js">
<div id="body-container">
<!-- Provide site root to javascript -->
<script>
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('light')
html.classList.add(theme);
var body = document.querySelector('body');
body.classList.remove('no-js')
body.classList.add('js');
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var body = document.querySelector('body');
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
body.classList.remove('sidebar-visible');
body.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded "><a href="../index.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="start/index.html"><strong aria-hidden="true">2.</strong> Quick Start</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="start/iso.html"><strong aria-hidden="true">2.1.</strong> ISO</a></li></ol></li><li class="chapter-item expanded "><a href="concepts/index.html"><strong aria-hidden="true">3.</strong> Key Concepts</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="concepts/hosts.html"><strong aria-hidden="true">3.1.</strong> Hosts</a></li><li class="chapter-item expanded "><a href="concepts/overrides.html"><strong aria-hidden="true">3.2.</strong> Overrides</a></li><li class="chapter-item expanded "><a href="concepts/profiles.html"><strong aria-hidden="true">3.3.</strong> Profiles</a></li><li class="chapter-item expanded "><a href="concepts/suites.html"><strong aria-hidden="true">3.4.</strong> Suites</a></li><li class="chapter-item expanded "><a href="concepts/users.html"><strong aria-hidden="true">3.5.</strong> Users</a></li></ol></li><li class="chapter-item expanded "><a href="outputs/index.html"><strong aria-hidden="true">4.</strong> Outputs</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="outputs/modules.html"><strong aria-hidden="true">4.1.</strong> Modules</a></li><li class="chapter-item expanded "><a href="outputs/overlays.html"><strong aria-hidden="true">4.2.</strong> Overlays</a></li><li class="chapter-item expanded "><a href="outputs/pkgs.html"><strong aria-hidden="true">4.3.</strong> Packages</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">5.</strong> Concerns</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="secrets.html"><strong aria-hidden="true">5.1.</strong> Secrets</a></li><li class="chapter-item expanded "><a href="tests.html"><strong aria-hidden="true">5.2.</strong> Tests</a></li></ol></li><li class="chapter-item expanded "><a href="integrations/index.html"><strong aria-hidden="true">6.</strong> Integrations</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="integrations/cachix.html"><strong aria-hidden="true">6.1.</strong> Cachix</a></li><li class="chapter-item expanded "><a href="integrations/deploy.html"><strong aria-hidden="true">6.2.</strong> Deploy RS</a></li><li class="chapter-item expanded "><a href="integrations/nvfetcher.html"><strong aria-hidden="true">6.3.</strong> NvFetcher</a></li><li class="chapter-item expanded "><a href="integrations/hercules.html"><strong aria-hidden="true">6.4.</strong> Hercules CI</a></li></ol></li><li class="chapter-item expanded "><a href="api-reference.html"><strong aria-hidden="true">7.</strong> API Reference</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="api-reference-channels.html"><strong aria-hidden="true">7.1.</strong> Channels</a></li><li class="chapter-item expanded "><a href="api-reference-home.html"><strong aria-hidden="true">7.2.</strong> Home</a></li><li class="chapter-item expanded "><a href="api-reference-devshell.html"><strong aria-hidden="true">7.3.</strong> Devshell</a></li><li class="chapter-item expanded "><a href="api-reference-nixos.html"><strong aria-hidden="true">7.4.</strong> NixOS</a></li></ol></li><li class="chapter-item expanded "><div><strong aria-hidden="true">8.</strong> Library Reference</div></li><li class="chapter-item expanded "><a href="CONTRIBUTING.html"><strong aria-hidden="true">9.</strong> Contributing</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<!-- Track and set sidebar scroll position -->
<script>
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
sidebarScrollbox.addEventListener('click', function(e) {
if (e.target.tagName === 'A') {
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
}
}, { passive: true });
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
sessionStorage.removeItem('sidebar-scroll');
if (sidebarScrollTop) {
// preserve sidebar scroll position when navigating via links within sidebar
sidebarScrollbox.scrollTop = sidebarScrollTop;
} else {
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
var activeSection = document.querySelector('#sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
</script>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Digga Library Docs</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<p><a href="https://mit-license.org"><img src="https://img.shields.io/github/license/divnix/devos" alt="MIT License" /></a>
<a href="https://nixos.org"><img src="https://img.shields.io/badge/NixOS-unstable-blue.svg?style=flat&amp;logo=NixOS&amp;logoColor=white" alt="NixOS" /></a>
<a href="https://matrix.to/#/#devos:nixos.org"><img src="https://img.shields.io/badge/chat-join%20us-brightgreen.svg?style=flat&amp;logo=matrix&amp;logoColor=white" alt="Chat" /></a></p>
<h1 id="deprecation-notice"><a class="header" href="#deprecation-notice">DEPRECATION NOTICE</a></h1>
<p>This project is no longer maintained and not recommended for any sort of use case. Please see https://github.com/divnix/digga/issues/503 for better alternatives and the reasons behind this decision.</p>
<hr />
<p>Digga — slangy German for "good friend" — is a flake utility library
that helps you declaratively craft and manage all three layers of your system
environment within a single <a href="https://wiki.nixos.org/wiki/Flakes">nix flakes</a> repository:</p>
<ul>
<li>development shells (via <a href="https://github.com/numtide/devshell"><code>numtide/devshell</code></a>),</li>
<li>home environments (via <a href="https://github.com/nix-community/home-manager"><code>nix-community/home-manager</code></a>), and</li>
<li>host configurations (via <a href="https://github.com/nixos/nixpkgs"><code>NixOS/nixpkgs/nixos</code></a>).</li>
</ul>
<p>This library is based on <a href="https://github.com/gytis-ivaskevicius/flake-utils-plus">flake-utils-plus</a>.</p>
<h1 id="status-beta"><a class="header" href="#status-beta">Status: Beta</a></h1>
<p>Although this project has already matured quite a bit, a fair amount of api polishing is still
expected. There are unstable versions (0.<em>x</em>.<em>x</em>) to help users keep track
of changes and progress.</p>
<h1 id="usage"><a class="header" href="#usage">Usage</a></h1>
<p>The best way to make use of library is with the <a href=".././examples/devos">Official template</a>.
Check out the <a href=".././doc/start/index.html">guide</a> to get up and running.
Also have a look at devos's <a href=".././examples/devos/flake.nix"><em>flake.nix</em></a>.
If anything is not immediately discoverable via our <a href=".././src/mkFlake"><code>mkFlake</code></a>, please file a bug report.</p>
<h1 id="examples"><a class="header" href="#examples">Examples</a></h1>
<p>Make sure to check out all the <a href=".././examples">examples</a> to see the different ways
to make use of the digga api.</p>
<h2 id="in-the-wild"><a class="header" href="#in-the-wild">In the Wild</a></h2>
<p>You can also see digga being actually used:</p>
<ul>
<li>@Pacman99: <a href="https://gitlab.com/coffeetables/lower">Personal</a>, <a href="https://gitlab.com/coffeetables/myrdd">Server</a></li>
<li><a href="https://github.com/danielphan2003/flk">@danielphan2003</a> and make sure to also check out <a href="https://github.com/divnix/devos-ext-lib">devos-ext-lib</a></li>
<li><a href="https://git.sr.ht/~b12f/pub-solar-os">PubSolarOS</a></li>
<li>@montchr: <a href="https://github.com/montchr/dotfield">Dotfield</a> – including darwin configurations</li>
<li><a href="https://github.com/sweenu/nixfiles">@sweenu</a>: pc, server and RaspberryPi deployment in one repo</li>
</ul>
<h1 id="philosophy"><a class="header" href="#philosophy">Philosophy</a></h1>
<p>In it's <code>lib.mkFlake</code> function, <em>Digga</em> implements a well-specified API
interface comprising four API containers that allow you to:</p>
<ol>
<li>
<p>configure <strong>nixpkgs channels</strong> including internal and external overlays,</p>
</li>
<li>
<p>define <strong>NixOS hosts</strong> including internal and external NixOS modules as well as
host defaults that apply to all hosts in the environment,</p>
</li>
<li>
<p>specify <strong>user home environments</strong> including internal and external home-manager
modules, and</p>
</li>
<li>
<p>setup &amp; combine a series of <strong>devshells</strong> that you like to have available in
your projects.</p>
</li>
</ol>
<h2 id="modules-profiles--suites"><a class="header" href="#modules-profiles--suites">Modules, Profiles &amp; Suites</a></h2>
<p>For NixOS- &amp; home-manager-modules, <em>Digga</em> allows you to distinguish between
<em>modules</em>, <em>profiles</em> and <em>suites</em>.</p>
<ul>
<li>
<p><strong>Modules</strong> are abstract configurations that, while holding the implementation, do not
set any system state.</p>
</li>
<li>
<p><strong>Profiles</strong> are concrete configurations that set system state within the profile domain.</p>
</li>
<li>
<p><strong>Suites</strong> are a composable, clean and discoverable mechanism for profile aggregation.</p>
</li>
</ul>
<h2 id="internal-art-vs-external-art"><a class="header" href="#internal-art-vs-external-art">Internal Art vs External Art</a></h2>
<p>Overlays and modules can be defined internally coming from your repo or externally
coming from an upstream flake. This distinction serves the library to only export
your own work as the public flake output.</p>
<p>Downstream consumers of your flake can now more easily tell your art apart from
other upstream art.</p>
<h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
<p>We encourage contributions of any kind. The simplest way to get involved is to
join the <a href="https://matrix.to/#/#devos:matrix.org">chat</a> or report problems and ideas on the <a href="https://github.com/divnix/digga/issues">issue thread</a>.</p>
<p>To craft well thought out APIs we need all the thoughts regarding new ideas.</p>
<p>Pull Requests are just as amazing.</p>
<h1 id="why-flakes"><a class="header" href="#why-flakes">Why <em>flakes</em>?</a></h1>
<p>Flakes are a part of an explicit push to improve <a href="https://github.com/NixOS/nix/blob/master/doc/manual/src/contributing/cli-guideline.md">Nix's UX</a>, and have become an integral part of that effort.</p>
<p>They also make <a href="https://nixos.org/manual/nix/unstable/expressions/expression-syntax.html">Nix expressions</a> easier to distribute and reuse with convient <a href="https://github.com/NixOS/nix/blob/master/src/nix/flake.md#flake-references">flake references</a> for building or using packages, modules, and whole systems.</p>
<h1 id="shoulders"><a class="header" href="#shoulders">Shoulders</a></h1>
<p>This work does not reinvent the wheel. It stands on the <a href="https://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants">shoulders of the
following giants</a>:</p>
<h2 id="onion--like-the-layers-of-an-onion"><a class="header" href="#onion--like-the-layers-of-an-onion">:onion: — like the layers of an onion</a></h2>
<ul>
<li><a href="https://github.com/gytis-ivaskevicius/flake-utils-plus"><code>gytis-ivaskevicius/flake-utils-plus</code></a></li>
<li><a href="https://github.com/numtide/flake-utils/"><code>numtide/flake-utils</code></a></li>
</ul>
<h2 id="family--like-family"><a class="header" href="#family--like-family">:family: — like family</a></h2>
<ul>
<li><a href="https://github.com/numtide/devshell"><code>numtide/devshell</code></a></li>
<li><a href="https://github.com/serokell/deploy-rs"><code>serokell/deploy-rs</code></a></li>
<li><a href="https://github.com/berberman/nvfetcher"><code>berberman/nvfetcher</code></a></li>
<li><a href="https://github.com/NixOS/nixpkgs"><code>NixOS/nixpkgs</code></a></li>
</ul>
<p>:heart:</p>
<h3 id="inspiration--art"><a class="header" href="#inspiration--art">Inspiration &amp; Art</a></h3>
<ul>
<li><a href="https://github.com/hlissner/dotfiles">hlissner/dotfiles</a></li>
<li><a href="https://github.com/nix-community/nix-user-chroot">nix-user-chroot</a></li>
<li><a href="https://github.com/tweag/nickel">Nickel</a></li>
<li><a href="https://github.com/nix-community/awesome-nix">Awesome Nix</a></li>
<li><a href="https://github.com/numtide/devshell">devshell</a></li>
</ul>
<h1 id="divnix"><a class="header" href="#divnix">Divnix</a></h1>
<p>The divnix org is an open space that spontaneously formed out of "the Nix".
It is really just a place where otherwise unrelated people work
together and get stuff done.</p>
<p>It's a place to stop "geeking out in isolation" (or within company boundaries).
A place to experiment, learn together, and iterate quickly on best practices.
That's what it is.</p>
<p>It might eventually become a non-profit if that's not too complicated or, if those
goals are sufficiently upstreamed into "the Nix", dissolved.</p>
<h1 id="license"><a class="header" href="#license">License</a></h1>
<p>Digga is licensed under the <a href="https://mit-license.org">MIT License</a>.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h1>
<p>The only dependency is nix, so make sure you have it <a href="https://nixos.org/manual/nix/stable/#sect-multi-user-installation">installed</a>.</p>
<h2 id="get-the-template"><a class="header" href="#get-the-template">Get the Template</a></h2>
<p>If you currently don't have flakes setup, you can utilize the digga shell to
pull the template:</p>
<pre><code class="language-sh">nix-shell "https://github.com/divnix/digga/archive/main.tar.gz" \
--run "nix flake init -t github:divnix/digga"
</code></pre>
<p>If you already have flakes support, you can directly pull the template:</p>
<pre><code class="language-sh">nix flake init -t github:divnix/digga
</code></pre>
<p>Then make sure to create the git repository:</p>
<pre><code class="language-sh">git init
git add .
git commit
</code></pre>
<p>Finally, run <code>nix-shell</code> to get to an interactive shell with all the
dependencies, including the unstable nix version required. You can run <code>menu</code> to
confirm that you are using digga (expected output includes [docs], [general
commands], [linter], etc.).</p>
<p>In addition, the <a href="start/../integrations/cachix.html">binary cache</a> is added for faster deployment.</p>
<blockquote>
<h1 id="notes"><a class="header" href="#notes"><em>Notes:</em></a></h1>
<ul>
<li>Flakes ignore files that have not been added to git, so be sure to stage new
files before building the system.</li>
<li>You can choose to simply clone the repo with git if you want to follow
upstream changes.</li>
<li>If the <code>nix-shell -p cachix --run "cachix use nrdxp"</code> line doesn't work you
can try with sudo: <code>sudo nix-shell -p cachix --run "cachix use nrdxp"</code></li>
</ul>
</blockquote>
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
<ul>
<li><a href="start/./iso.html">Make installable ISO</a></li>
</ul>
<div style="break-before: page; page-break-before: always;"></div><h1 id="installation-media"><a class="header" href="#installation-media">Installation Media</a></h1>
<p>This project leverages <a href="https://github.com/nix-community/nixos-generators">nix-community/nixos-generators</a> for
building machine images. In most cases, you'll probably want to use the
<code>install-iso</code> format.</p>
<p>Making an installable ISO for <code>hosts/bootstrap.nix</code> is as simple as:</p>
<pre><code class="language-sh">nix run github:nix-community/nixos-generators -- \
--format install-iso \
--flake '.#bootstrap'
</code></pre>
<p>Then "burn" the ISO to your USB stick (or CD-R if you like!) following the
<a href="https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb">instructions in the NixOS manual</a> (or using your preferred USB burner).</p>
<p>You can also swap out the <code>--format</code> for <a href="https://github.com/nix-community/nixos-generators/tree/master/formats">any of the others</a> supported
by nixos-generators.</p>
<p>Continue by following the usual installation instructions in the NixOS manual.</p>
<h2 id="iso-nix-store-and-cache"><a class="header" href="#iso-nix-store-and-cache">ISO Nix Store and Cache</a></h2>
<p>The ISO image holds the Nix store for the live environment and <em>also</em> acts as a
binary cache to the installer. To considerably speed things up, the image
already includes all flake <code>inputs</code> as well as the <code>devshell</code> closures.</p>
<p>While you <em>could</em> provision any NixOS machine with the same USB stick, an ISO
custom-made for your target host will maximise 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.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="key-concepts"><a class="header" href="#key-concepts">Key Concepts</a></h1>
<p>Key concepts are derived from <a href="https://github.com/divnix/digga">digga</a>. Please refer to its
<a href="https://digga.divnix.com">docs</a> for more details.</p>
<p>This section is dedicated to helping you develop a more hands on
understanding of them them.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="hosts"><a class="header" href="#hosts">Hosts</a></h1>
<p>Nix flakes contain an output called <code>nixosConfigurations</code> declaring an
attribute set of valid NixOS systems. To simplify the management and creation
of these hosts, devos automatically imports every <em>.nix</em> 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.</p>
<p>As an example, a file <code>hosts/system.nix</code> or <code>hosts/system/default.nix</code> will
be available via the flake output <code>nixosConfigurations.system</code>. You can have
as many hosts as you want and all of them will be automatically imported based
on their name.</p>
<p>For each host, the configuration automatically sets the <code>networking.hostName</code>
attribute to the folder name or name of the file minus the <em>.nix</em> extension. This
is for convenience, since <code>nixos-rebuild</code> automatically searches for a configuration
matching the current systems hostname if one is not specified explicitly.</p>
<p>You can set channels, systems, and add extra modules to each host by editing the
<code>nixos.hosts</code> argument in flake.nix. This is the perfect place to import
host specific modules from external sources, such as the
<a href="https://github.com/NixOS/nixos-hardware">nixos-hardware</a> repository.</p>
<p>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 <a href="concepts/./profiles.html">profile modules</a>.</p>
<p>This is a good place to import sets of profiles, called <a href="concepts/./suites.html">suites</a>,
that you intend to use on your machine.</p>
<h2 id="example"><a class="header" href="#example">Example</a></h2>
<p>flake.nix:</p>
<pre><code class="language-nix">{
nixos = {
imports = [ (devos.lib.importHosts ./hosts) ];
hosts = {
librem = {
channelName = "latest";
modules = [ nixos-hardware.nixosModules.purism-librem-13v3 ];
};
};
};
}
</code></pre>
<p>hosts/librem.nix:</p>
<pre><code class="language-nix">{ suites, ... }:
{
imports = suites.laptop;
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
}
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="overrides"><a class="header" href="#overrides">Overrides</a></h1>
<p>Each NixOS host follows one channel. But many times it is useful to get packages
or modules from different channels.</p>
<h2 id="packages"><a class="header" href="#packages">Packages</a></h2>
<p>You can make use of <code>overlays/overrides.nix</code> 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 <code>channels</code> as their first argument.</p>
<p>You can add overlays to any channel to override packages from other channels.</p>
<p>Pulling the manix package from the <code>latest</code> channel:</p>
<pre><code class="language-nix">channels: final: prev: {
__dontExport = true;
inherit (pkgs.latest) manix;
}
</code></pre>
<p>It is recommended to set the <code>__dontExport</code> property for override specific
overlays. <code>overlays/overrides.nix</code> is the best place to consolidate all package
overrides and the property is already set for you.</p>
<h2 id="modules"><a class="header" href="#modules">Modules</a></h2>
<p>You can also pull modules from other channels. All modules have access to the
<code>modulesPath</code> for each channel as <code>&lt;channelName&gt;ModulesPath</code>. And you can use
<code>disabledModules</code> to remove modules from the current channel.</p>
<p>To pull zsh module from the <code>latest</code> channel this code can be placed in any module, whether its your host file, a profile, or a module in ./modules etc:</p>
<pre><code class="language-nix">{ latestModulesPath }:
{
imports = [ "${latestModulesPath}/programs/zsh/zsh.nix" ];
disabledModules = [ "programs/zsh/zsh.nix" ];
}
</code></pre>
<blockquote>
<h5 id="note"><a class="header" href="#note"><em>Note:</em></a></h5>
<p>Sometimes a modules name will change from one branch to another.</p>
</blockquote>
<div style="break-before: page; page-break-before: always;"></div><h1 id="profiles"><a class="header" href="#profiles">Profiles</a></h1>
<p>Profiles are a convenient shorthand for the <a href="https://nixos.org/manual/nixos/stable/index.html#sec-option-definitions"><em>definition</em></a> of
<a href="https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules">options</a> in contrast to their <a href="https://nixos.org/manual/nixos/stable/index.html#sec-option-declarations"><em>declaration</em></a>. They're
built into the NixOS module system for a reason: to elegantly provide a clear
separation of concerns.</p>
<h2 id="creation"><a class="header" href="#creation">Creation</a></h2>
<p>Profiles are created with the <code>rakeLeaves</code> function which recursively collects
<code>.nix</code> files from within a folder. The recursion stops at folders with a <code>default.nix</code>
in them. You end up with an attribute set with leaves(paths to profiles) or
nodes(attrsets leading to more nodes or leaves).</p>
<p>A profile is used for quick modularization of <a href="concepts/./profiles.html#subprofiles">interelated bits</a>.</p>
<blockquote>
<h5 id="notes-1"><a class="header" href="#notes-1"><em>Notes:</em></a></h5>
<ul>
<li>For <em>declaring</em> module options, there's the <a href="concepts/../outputs/modules.html">modules</a> directory.</li>
<li>This directory takes inspiration from
<a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/profiles">upstream</a>
.</li>
</ul>
</blockquote>
<h3 id="nested-profiles"><a class="header" href="#nested-profiles">Nested profiles</a></h3>
<p>Profiles can be nested in attribute sets due to the recursive nature of <code>rakeLeaves</code>.
This can be useful to have a set of profiles created for a specific purpose. It is
sometimes useful to have a <code>common</code> profile that has high level concerns related
to all its sister profiles.</p>
<h3 id="example-1"><a class="header" href="#example-1">Example</a></h3>
<p>profiles/develop/common.nix:</p>
<pre><code class="language-nix">{
imports = [ ./zsh ];
# some generic development concerns ...
}
</code></pre>
<p>profiles/develop/zsh.nix:</p>
<pre><code class="language-nix">{ ... }:
{
programs.zsh.enable = true;
# zsh specific options ...
}
</code></pre>
<p>The examples above will end up with a profiles set like this:</p>
<pre><code class="language-nix">{
develop = {
common = ./profiles/develop/common.nix;
zsh = ./profiles/develop/zsh.nix;
};
}
</code></pre>
<h2 id="conclusion"><a class="header" href="#conclusion">Conclusion</a></h2>
<p>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 <a href="concepts/hosts.html">host</a> files instead.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="suites"><a class="header" href="#suites">Suites</a></h1>
<p>Suites provide a mechanism for users to easily combine and name collections of
profiles.</p>
<p><code>suites</code> are defined in the <code>importables</code> argument in either the <code>home</code> or <code>nixos</code>
namespace. They are a special case of an <code>importable</code> which is passed as a special
argument (one that can be use in an <code>imports</code> line) to your hosts. All lists defined
in <code>suites</code> are flattened and type-checked as paths.</p>
<h2 id="definition"><a class="header" href="#definition">Definition</a></h2>
<pre><code class="language-nix">rec {
workstation = [ profiles.develop profiles.graphical users.nixos ];
mobileWS = workstation ++ [ profiles.laptop ];
}
</code></pre>
<h2 id="usage-1"><a class="header" href="#usage-1">Usage</a></h2>
<p><code>hosts/my-laptop.nix</code>:</p>
<pre><code class="language-nix">{ suites, ... }:
{
imports = suites.mobileWS;
}
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><blockquote>
<h5 id="note-1"><a class="header" href="#note-1"><em>Note:</em></a></h5>
<p>This section and its semantics need a conceptiual rework.
Since recently <a href="https://digga.divnix.com/api-reference-home.html#homeusers">portable home configurations</a>
that are not bound to any specific host are a thing.</p>
</blockquote>
<h1 id="users"><a class="header" href="#users">Users</a></h1>
<p>Users are a special case of <a href="concepts/profiles.html">profiles</a> that define system
users and <a href="https://nix-community.github.io/home-manager">home-manager</a> configurations. For your convenience,
home manager is wired in by default so all you have to worry about is declaring
your users.</p>
<h2 id="basic-usage"><a class="header" href="#basic-usage">Basic Usage</a></h2>
<p><code>users/myuser/default.nix</code>:</p>
<pre><code class="language-nix">{ ... }:
{
users.users.myuser = {
isNormalUser = true;
};
home-manager.users.myuser = {
programs.mpv.enable = true;
};
}
</code></pre>
<h2 id="home-manager"><a class="header" href="#home-manager">Home Manager</a></h2>
<p>Home Manager support follows the same principles as regular nixos configurations,
it even gets its own namespace in your <code>flake.nix</code> as <code>home</code>.</p>
<p>All modules defined in <a href="https://github.com/divnix/digga/tree/main/users/modules/module-list.nix">user modules</a> will be imported to
Home Manager.
User profiles can be collected in a similar fashion as system ones into a <code>suites</code>
argument that gets passed to your home-manager users.</p>
<h3 id="example-2"><a class="header" href="#example-2">Example</a></h3>
<p><code>flake.nix</code></p>
<pre><code class="language-nix">{
home.users.nixos = { suites, ... }: {
imports = suites.base;
};
}
</code></pre>
<h2 id="external-usage"><a class="header" href="#external-usage">External Usage</a></h2>
<p>You can easily use the defined home-manager configurations outside of NixOS
using the <code>homeConfigurations</code> flake output.</p>
<p>This is great for keeping your environment consistent across Unix-like systems,
including macOS.</p>
<pre><code class="language-sh"># build
nix build "github:divnix/devos#homeConfigurations.nixos@NixOS.home.activationPackage"
# activate
./result/activate &amp;&amp; unlink result
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="layout"><a class="header" href="#layout">Layout</a></h1>
<p>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.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="modules-1"><a class="header" href="#modules-1">Modules</a></h1>
<p>The modules directory is a replica of nixpkg's NixOS <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">modules</a>
, and follows the same semantics. This allows for trivial upstreaming into
nixpkgs proper once your module is sufficiently stable.</p>
<p>All modules linked in <em>module-list.nix</em> are automatically exported via
<code>nixosModules.&lt;file-basename&gt;</code>, and imported into all <a href="outputs/../concepts/hosts.html">hosts</a>.</p>
<blockquote>
<h5 id="note-2"><a class="header" href="#note-2"><em>Note:</em></a></h5>
<p>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 <a href="outputs/../concepts/profiles.html">profiles</a> instead.</p>
</blockquote>
<h2 id="semantics"><a class="header" href="#semantics">Semantics</a></h2>
<p>In case you've never written a module for nixpkgs before, here is a brief
outline of the process.</p>
<h3 id="declaration"><a class="header" href="#declaration">Declaration</a></h3>
<p>modules/services/service-category/my-service.nix:</p>
<pre><code class="language-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 ...
};
}
</code></pre>
<h3 id="import"><a class="header" href="#import">Import</a></h3>
<p>modules/module-list.nix:</p>
<pre><code class="language-nix">[
./services/service-category/my-service.nix
]
</code></pre>
<h2 id="usage-2"><a class="header" href="#usage-2">Usage</a></h2>
<h3 id="internal"><a class="header" href="#internal">Internal</a></h3>
<p>profiles/profile-category/my-profile.nix:</p>
<pre><code class="language-nix">{ ... }:
{
services.MyService.enable = true;
}
</code></pre>
<h3 id="external"><a class="header" href="#external">External</a></h3>
<p>flake.nix:</p>
<pre><code class="language-nix">{
# inputs omitted
outputs = { self, devos, nixpkgs, ... }: {
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
system = "...";
modules = [
devos.nixosModules.my-service
({ ... }: {
services.MyService.enable = true;
})
];
};
};
}
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="overlays"><a class="header" href="#overlays">Overlays</a></h1>
<p>Writing overlays is a common occurence when using a NixOS system. Therefore,
we want to keep the process as simple and straightforward as possible.</p>
<p>Any <em>.nix</em> files declared in this directory will be assumed to be a valid
overlay, and will be automatically imported into all <a href="outputs/../concepts/hosts.html">hosts</a>, and
exported via <code>overlays.&lt;channel&gt;/&lt;pkgName&gt;</code> <em>as well as</em>
<code>packages.&lt;system&gt;.&lt;pkgName&gt;</code> (for valid systems), so all you have to do is
write it.</p>
<h2 id="example-3"><a class="header" href="#example-3">Example</a></h2>
<p>overlays/kakoune.nix:</p>
<pre><code class="language-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
];
};
}
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="packages-1"><a class="header" href="#packages-1">Packages</a></h1>
<p>Similar to <a href="outputs/./modules.html">modules</a>, the pkgs directory mirrors the upstream
<a href="https://github.com/NixOS/nixpkgs/tree/master/pkgs">nixpkgs/pkgs</a>, 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.</p>
<p>The only minor difference is that, instead of adding the <code>callPackage</code> call to
<code>all-packages.nix</code>, you just add it the the <em>default.nix</em> in this directory,
which is defined as a simple overlay.</p>
<p>All the packages are exported via <code>packages.&lt;system&gt;.&lt;pkg-name&gt;</code>, for all
the supported systems listed in the package's <code>meta.platforms</code> attribute.</p>
<p>And, as usual, every package in the overlay is also available to any NixOS
<a href="outputs/../concepts/hosts.html">host</a>.</p>
<p>Another convenient difference is that it is possible to use
<a href="https://github.com/berberman/nvfetcher">nvfetcher</a> to keep packages up to
date.
This is best understood by the simple example below.</p>
<h2 id="example-4"><a class="header" href="#example-4">Example</a></h2>
<p>It is possible to specify sources separately to keep them up to date semi
automatically.
The basic rules are specified in pkgs/sources.toml:</p>
<pre><code class="language-toml"># nvfetcher.toml
[libinih]
src.github = "benhoyt/inih"
fetch.github = "benhoyt/inih"
</code></pre>
<p>After changes to this file as well as to update the packages specified in there run
nvfetcher (for more details see <a href="https://github.com/berberman/nvfetcher">nvfetcher</a>).</p>
<p>The pkgs overlay is managed in
pkgs/default.nix:</p>
<pre><code class="language-nix">final: prev: {
# keep sources first, this makes sources available to the pkgs
sources = prev.callPackage (import ./_sources/generated.nix) { };
# then, call packages with `final.callPackage`
libinih = prev.callPackage ./development/libraries/libinih { };
}
</code></pre>
<p>Lastly the example package is in
pkgs/development/libraries/libinih/default.nix:</p>
<pre><code class="language-nix">{ stdenv, meson, ninja, lib, sources, ... }:
stdenv.mkDerivation {
pname = "libinih";
# version will resolve to the latest available on gitub
inherit (sources.libinih) version src;
buildInputs = [ meson ninja ];
# ...
}
</code></pre>
<h2 id="migration-from-flake-based-approach"><a class="header" href="#migration-from-flake-based-approach">Migration from flake based approach</a></h2>
<p>Previous to nvfetcher it was possible to manage sources via a pkgs/flake.nix, the main changes from there are that sources where in the attribute "srcs" (now "sources") and the contents of the sources where slightly different.
In order to switch to the new system, rewrite pkgs/flake.nix to a pkgs/sources.toml file using the documentation of nvfetcher,
add the line that calls the sources at the beginning of pkgs/default.nix, and
accomodate the small changes in the packages as can be seen from the example.</p>
<p>The example package looked like:</p>
<p>pkgs/flake.nix:</p>
<pre><code class="language-nix">{
description = "Package sources";
inputs = {
libinih.url = "github:benhoyt/inih/r53";
libinih.flake = false;
};
}
</code></pre>
<p>pkgs/default.nix:</p>
<pre><code class="language-nix">final: prev: {
# then, call packages with `final.callPackage`
libinih = prev.callPackage ./development/libraries/libinih { };
}
</code></pre>
<p>pkgs/development/libraries/libinih/default.nix:</p>
<pre><code class="language-nix">{ stdenv, meson, ninja, lib, srcs, ... }:
let inherit (srcs) libinih; in
stdenv.mkDerivation {
pname = "libinih";
# version will resolve to 53, as specified in the flake.nix file
inherit (libinih) version;
src = libinih;
buildInputs = [ meson ninja ];
# ...
}
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="secrets"><a class="header" href="#secrets">Secrets</a></h1>
<p>Secrets are managed using <a href="https://github.com/ryantm/agenix">agenix</a>
so you can keep your flake in a public repository like GitHub without
exposing your password or other sensitive data.</p>
<h2 id="agenix"><a class="header" href="#agenix">Agenix</a></h2>
<p>Currently, there is <a href="https://github.com/NixOS/nix/issues/8">no mechanism</a> in nix itself to deploy secrets
within the nix store because it is world-readable.</p>
<p>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 <a href="https://github.com/ryantm/agenix">agenix</a>
to easily setup those secret files declaratively.</p>
<p><a href="https://github.com/ryantm/agenix">agenix</a> 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 <a href="https://github.com/ryantm/agenix/blob/master/modules/age.nix">age module</a> will add those
encrypted files to the nix store and decrypt them on activation to <code>/run/agenix</code>.</p>
<h3 id="setup"><a class="header" href="#setup">Setup</a></h3>
<p>All hosts must have openssh enabled, this is done by default in the core profile.</p>
<p>You need to populate your <code>secrets/secrets.nix</code> with the proper ssh public keys.
Be extra careful to make sure you only add public keys, you should never share a
private key!!</p>
<p>secrets/secrets.nix:</p>
<pre><code class="language-nix">let
system = "&lt;system ssh key&gt;";
user = "&lt;user ssh key&gt;";
allKeys = [ system user ];
in
</code></pre>
<p>On most systems, you can get your systems ssh public key from <code>/etc/ssh/ssh_host_ed25519_key.pub</code>. If
this file doesn't exist you likely need to enable openssh and rebuild your system.</p>
<p>Your users ssh public key is probably stored in <code>~/.ssh/id_ed25519.pub</code> or
<code>~/.ssh/id_rsa.pub</code>. If you haven't generated a ssh key yet, be sure do so:</p>
<pre><code class="language-sh">ssh-keygen -t ed25519
</code></pre>
<blockquote>
<h5 id="note-3"><a class="header" href="#note-3"><em>Note:</em></a></h5>
<p>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.</p>
</blockquote>
<h3 id="secrets-1"><a class="header" href="#secrets-1">Secrets</a></h3>
<p>You will need the <code>agenix</code> command to create secrets. DevOS conveniently provides that
in the devShell, so just run <code>nix develop</code> whenever you want to edit secrets. Make sure
to always run <code>agenix</code> while in the <code>secrets/</code> folder, so it can pick up your <code>secrets.nix</code>.</p>
<p>To create secrets, simply add lines to your <code>secrets/secrets.nix</code>:</p>
<pre><code>let
...
allKeys = [ system user ];
in
{
"secret.age".publicKeys = allKeys;
}
</code></pre>
<p>That would tell agenix to create a <code>secret.age</code> file that is encrypted with the <code>system</code>
and <code>user</code> ssh public key.</p>
<p>Then go into the <code>secrets</code> folder and run:</p>
<pre><code class="language-sh">agenix -e secret.age
</code></pre>
<p>This will create the <code>secret.age</code>, if it doesn't already exist, and allow you to edit it.</p>
<p>If you ever change the <code>publicKeys</code> entry of any secret make sure to rekey the secrets:</p>
<pre><code class="language-sh">agenix --rekey
</code></pre>
<h3 id="usage-3"><a class="header" href="#usage-3">Usage</a></h3>
<p>Once you have your secret file encrypted and ready to use, you can utilize the <a href="https://github.com/ryantm/agenix/blob/master/modules/age.nix">age module</a>
to ensure that your secrets end up in <code>/run/secrets</code>.</p>
<p>In any profile that uses a NixOS module that requires a secret you can enable a particular secret like so:</p>
<pre><code class="language-nix">{ self, ... }:
{
age.secrets.mysecret.file = "${self}/secrets/mysecret.age";
}
</code></pre>
<p>Then you can just pass the path <code>/run/agenix/mysecret</code> to the module.</p>
<p>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
<a href="https://github.com/ryantm/agenix/blob/master/modules/age.nix">age module</a>.</p>
<blockquote>
<h5 id="note-4"><a class="header" href="#note-4"><em>Note:</em></a></h5>
<p>You can take a look at the <a href="https://github.com/ryantm/agenix">agenix repository</a> for more information
about the tool.</p>
</blockquote>
<div style="break-before: page; page-break-before: always;"></div><h1 id="testing"><a class="header" href="#testing">Testing</a></h1>
<p>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
<a href="./integrations/hercules.html">CI</a>.</p>
<h2 id="unit-tests"><a class="header" href="#unit-tests">Unit Tests</a></h2>
<p>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 <a href="https://nixos.org/manual/nixpkgs/stable/#ssec-check-phase">check phase</a>. All packages and their tests will
be built during CI.</p>
<h2 id="integration-tests"><a class="header" href="#integration-tests">Integration Tests</a></h2>
<p>All your profiles defined in suites can be tested against an individual host.
Simply use digga's pre-baked <code>digga.lib.allProfilesTest</code> like so:</p>
<pre><code class="language-nix">{
hosts = {
Morty.tests = [ allProfilesTest ];
};
}
</code></pre>
<p>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!</p>
<p>Be sure to use the <code>mkTest</code> function from Digga, <code>digga.lib.mkTest</code>
which wraps the official <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/lib/testing-python.nix">testing-python</a> 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 <a href="https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests">docs</a>, a fantastic <a href="https://www.haskellforall.com/2020/11/how-to-use-nixos-for-lightweight.html">blog post</a>,
and the examples in <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixpkgs</a>.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="integrations"><a class="header" href="#integrations">Integrations</a></h1>
<p>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.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="cachix"><a class="header" href="#cachix">Cachix</a></h1>
<p>The system will automatically pull a cachix.nix at the root if one exists.
This is usually created automatically by a <code>sudo cachix use</code>. If you're more
inclined to keep the root clean, you can drop any generated files in the
<code>cachix</code> directory into the <code>profiles/cachix</code> directory without further
modification.</p>
<p>For example, to add your own cache, assuming the template lives in /etc/nixos,
by simply running <code>sudo cachix use yourcache</code>. Then, optionally, move
<code>cachix/yourcache.nix</code> to <code>profiles/cachix/yourcache.nix</code></p>
<p>These caches are only added to the system after a <code>nixos-rebuild switch</code>, so it
is recommended to call <code>cachix use nrdxp</code> before the initial deployment, as it
will save a lot of build time.</p>
<p>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.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="deploy-rs"><a class="header" href="#deploy-rs">deploy-rs</a></h1>
<p><a href="https://github.com/serokell/deploy-rs">Deploy-rs</a> 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.</p>
<p>By default, all the <a href="integrations/../concepts/hosts.html">hosts</a> are also available as deploy-rs nodes,
configured with the hostname set to <code>networking.hostName</code>; overridable via
the command line.</p>
<h2 id="usage-4"><a class="header" href="#usage-4">Usage</a></h2>
<p>Just add your ssh key to the host:</p>
<pre><code class="language-nix">{ ... }:
{
users.users.${sshUser}.openssh.authorizedKeys.keyFiles = [
../secrets/path/to/key.pub
];
}
</code></pre>
<p>And the private key to your user:</p>
<pre><code class="language-nix">{ ... }:
{
home-manager.users.${sshUser}.programs.ssh = {
enable = true;
matchBlocks = {
${host} = {
host = hostName;
identityFile = ../secrets/path/to/key;
extraOptions = { AddKeysToAgent = "yes"; };
};
};
}
}
</code></pre>
<p>And run the deployment:</p>
<pre><code class="language-sh">deploy '.#hostName' --hostname host.example.com
</code></pre>
<blockquote>
<h5 id="note-5"><a class="header" href="#note-5"><em>Note:</em></a></h5>
<p>Your user will need <strong>passwordless</strong> sudo access</p>
</blockquote>
<h3 id="home-manager-1"><a class="header" href="#home-manager-1">Home Manager</a></h3>
<p>Digga's <code>lib.mkDeployNodes</code> provides only <code>system</code> profile.
In order to deploy your <code>home-manager</code> configuration you should provide additional profile(s) to deploy-rs config:</p>
<pre><code class="language-nix"># Initially, this line looks like this: deploy.nodes = digga.lib.mkDeployNodes self.nixosConfigurations { };
deploy.nodes = digga.lib.mkDeployNodes self.nixosConfigurations
{
&lt;HOSTNAME&gt; = {
profilesOrder = [ "system" "&lt;HM_PROFILE&gt;" "&lt;ANOTHER_HM_PROFILE&gt;"];
profiles.&lt;HM_PROFILE&gt; = {
user = "&lt;YOUR_USERNAME&gt;";
path = deploy.lib.x86_64-linux.activate.home-manager self.homeConfigurationsPortable.x86_64-linux.&lt;YOUR_USERNAME&gt;;
};
profiles.&lt;ANOTHER_HM_PROFILE&gt; = {
user = "&lt;ANOTHER_USERNAME&gt;";
path = deploy.lib.x86_64-linux.activate.home-manager self.homeConfigurationsPortable.x86_64-linux.&lt;ANOTHER_USERNAME&gt;;
};
};
};
</code></pre>
<p>Substitute <code>&lt;HOSTNAME&gt;</code>, <code>&lt;HM_PROFILE&gt;</code> and <code>&lt;YOUR_USERNAME&gt;</code> placeholders (omitting the <code>&lt;&gt;</code>).</p>
<p><code>&lt;ANOTHER_HM_PROFILE&gt;</code> is there to illustrate deploying multiple <code>home-manager</code> configurations. Either substitute those as well,
or remove them altogether. Don't forget the <code>profileOrder</code> variable.</p>
<div style="break-before: page; page-break-before: always;"></div><h1 id="nvfetcher"><a class="header" href="#nvfetcher">nvfetcher</a></h1>
<p><a href="https://github.com/berberman/nvfetcher">NvFetcher</a> is a workflow companion for updating nix sources.</p>
<p>You can specify an origin source and an update configuration, and
nvfetcher can for example track updates to a specific branch and
automatically update your nix sources configuration on each run
to the tip of that branch.</p>
<p>All package source declaration is done in <a href="https://github.com/divnix/devos/tree/main/pkgs/sources.toml">sources.toml</a>.</p>
<p>From within the devshell of this repo, run <code>nvfetcher</code>, a wrapped
version of <code>nvfetcher</code> that knows where to find and place its files
and commit the results.</p>
<h2 id="usage-5"><a class="header" href="#usage-5">Usage</a></h2>
<p>Statically fetching (not tracking) a particular tag from a github repo:</p>
<pre><code class="language-toml">[manix]
src.manual = "v0.6.3"
fetch.github = "mlvzk/manix"
</code></pre>
<p>Tracking the latest github <em>release</em> from a github repo:</p>
<pre><code class="language-toml">[manix]
src.github = "mlvzk/manix" # responsible for tracking
fetch.github = "mlvzk/manix" # responsible for fetching
</code></pre>
<p>Tracking the latest commit of a git repository and fetch from a git repo:</p>
<pre><code class="language-toml">[manix]
src.git = "https://github.com/mlvzk/manix.git" # responsible for tracking
fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
</code></pre>
<blockquote>
<h5 id="note-6"><a class="header" href="#note-6"><em>Note:</em></a></h5>
<p>Please refer to the <a href="https://github.com/berberman/nvfetcher#readme">NvFetcher Readme</a> for more options.</p>
</blockquote>
<div style="break-before: page; page-break-before: always;"></div><h1 id="hercules-ci"><a class="header" href="#hercules-ci">Hercules CI</a></h1>
<p>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 <a href="https://cachix.org">cachix</a>.</p>
<p>This will work whether your copy is a fork, or a bare template, as long as your
repo is hosted on GitHub.</p>
<h2 id="setup-1"><a class="header" href="#setup-1">Setup</a></h2>
<p>Just head over to <a href="https://hercules-ci.com">hercules-ci.com</a> to make an account.</p>
<p>Then follow the docs to set up an <a href="https://docs.hercules-ci.com/hercules-ci/getting-started/#github">agent</a>, if you want to deploy to a
binary cache (and of course you do), be sure <em>not</em> to skip the
<a href="https://docs.hercules-ci.com/hercules-ci/getting-started/deploy/nixos/#_3_configure_a_binary_cache">binary-caches.json</a>.</p>
<h2 id="ready-to-use"><a class="header" href="#ready-to-use">Ready to Use</a></h2>
<p>The repo is already set up with the proper <em>default.nix</em> file, building all
declared packages, checks, profiles and shells. So you can see if something
breaks, and never build the same package twice!</p>
<p>If you want to get fancy, you could even have hercules
<a href="https://docs.hercules-ci.com/hercules-ci-effects/guide/deploy-a-nixos-machine/">deploy your configuration</a>!</p>
<blockquote>
<h5 id="note-7"><a class="header" href="#note-7"><em>Note:</em></a></h5>
<p>Hercules doesn't have access to anything encrypted in the
<a href="integrations/../../secrets">secrets folder</a>, so none of your secrets will accidentally get
pushed to a cache by mistake.</p>
<p>You could pull all your secrets via your user, and then exclude it from
<a href="https://github.com/nrdxp/devos/blob/nrd/suites/default.nix#L17">allUsers</a>
to keep checks passing.</p>
</blockquote>
<div style="break-before: page; page-break-before: always;"></div><h1 id="top-level-api"><a class="header" href="#top-level-api">Top Level API</a></h1>
<p><code>digga</code>'s top level API. API Containers are documented in their respective sub-chapter:</p>
<ul>
<li><a href="./api-reference-channels.html">Channels</a></li>
<li><a href="./api-reference-home.html">Home</a></li>
<li><a href="./api-reference-devshell.html">Devshell</a></li>
<li><a href="./api-reference-nixos.html">NixOS</a></li>
<li><a href="./api-reference-darwin.html">Darwin</a></li>
</ul>
<h2 id="channelsconfig"><a class="header" href="#channelsconfig">channelsConfig</a></h2>
<p>nixpkgs config for all channels</p>
<p><em><em>Type</em></em>:
attribute set or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="inputs"><a class="header" href="#inputs">inputs</a></h2>
<p>The flake's inputs</p>
<p><em><em>Type</em></em>:
attribute set of nix flakes</p>
<h2 id="outputsbuilder"><a class="header" href="#outputsbuilder">outputsBuilder</a></h2>
<p>builder for flake system-spaced outputs
The builder gets passed an attrset of all channels</p>
<p><em><em>Type</em></em>:
function that evaluates to a(n) attribute set or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>"channels: { }"
</code></pre>
<h2 id="self"><a class="header" href="#self">self</a></h2>
<p>The flake to create the DevOS outputs for</p>
<p><em><em>Type</em></em>:
nix flake</p>
<h2 id="supportedsystems"><a class="header" href="#supportedsystems">supportedSystems</a></h2>
<p>The systems supported by this flake</p>
<p><em><em>Type</em></em>:
list of strings</p>
<p><em><em>Default</em></em></p>
<pre><code>["aarch64-linux","aarch64-darwin","x86_64-darwin","x86_64-linux"]
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="channels-api-container"><a class="header" href="#channels-api-container">Channels API Container</a></h1>
<p>Configure your channels that you can use throughout your configurations.</p>
<blockquote>
<h4 id="-gotcha-"><a class="header" href="#-gotcha-">⚠ Gotcha ⚠</a></h4>
<p>Devshell &amp; (non-host-specific) Home-Manager <code>pkgs</code> instances are rendered off the
<code>nixos.hostDefaults.channelName</code> (default) channel.</p>
</blockquote>
<h2 id="channels"><a class="header" href="#channels">channels</a></h2>
<p>nixpkgs channels to create</p>
<p><em><em>Type</em></em>:
attribute set of submodules or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="channelsnameconfig"><a class="header" href="#channelsnameconfig">channels.&lt;name&gt;.config</a></h2>
<p>nixpkgs config for this channel</p>
<p><em><em>Type</em></em>:
attribute set or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="channelsnameinput"><a class="header" href="#channelsnameinput">channels.&lt;name&gt;.input</a></h2>
<p>nixpkgs flake input to use for this channel</p>
<p><em><em>Type</em></em>:
nix flake</p>
<p><em><em>Default</em></em></p>
<pre><code>"self.inputs.&lt;name&gt;"
</code></pre>
<h2 id="channelsnameoverlays"><a class="header" href="#channelsnameoverlays">channels.&lt;name&gt;.overlays</a></h2>
<p>overlays to apply to this channel
these will get exported under the 'overlays' flake output
as &lt;channel&gt;/&lt;name&gt; and any overlay pulled from &lt;inputs&gt;
will be filtered out</p>
<p><em><em>Type</em></em>:
list of valid Nixpkgs overlay or path convertible to its or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="channelsnamepatches"><a class="header" href="#channelsnamepatches">channels.&lt;name&gt;.patches</a></h2>
<p>patches to apply to this channel</p>
<p><em><em>Type</em></em>:
list of paths</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="home-manager-api-container"><a class="header" href="#home-manager-api-container">Home-Manager API Container</a></h1>
<p>Configure your home manager modules, profiles &amp; suites.</p>
<h2 id="home"><a class="header" href="#home">home</a></h2>
<p>hosts, modules, suites, and profiles for home-manager</p>
<p><em><em>Type</em></em>:
submodule or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="homeexportedmodules"><a class="header" href="#homeexportedmodules">home.exportedModules</a></h2>
<p>modules to include in all hosts and export to homeModules output</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="homeexternalmodules"><a class="header" href="#homeexternalmodules">home.externalModules</a></h2>
<p>The <code>externalModules</code> option has been removed.
Any modules that should be exported should be defined with the <code>exportedModules</code>
option and all other modules should just go into the <code>modules</code> option.</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="homeimportables"><a class="header" href="#homeimportables">home.importables</a></h2>
<p>Packages of paths to be passed to modules as <code>specialArgs</code>.</p>
<p><em><em>Type</em></em>:
attribute set</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="homeimportablessuites"><a class="header" href="#homeimportablessuites">home.importables.suites</a></h2>
<p>collections of profiles</p>
<p><em><em>Type</em></em>:
null or attribute set of list of paths or anything convertible to its or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>null
</code></pre>
<h2 id="homemodules"><a class="header" href="#homemodules">home.modules</a></h2>
<p>modules to include that won't be exported
meant importing modules from external flakes</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="homeusers"><a class="header" href="#homeusers">home.users</a></h2>
<p>HM users that can be deployed portably without a host.</p>
<p><em><em>Type</em></em>:
attribute set of HM user configs</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="devshell-api-container"><a class="header" href="#devshell-api-container">Devshell API Container</a></h1>
<p>Configure your devshell module collections of your environment.</p>
<h2 id="devshell"><a class="header" href="#devshell">devshell</a></h2>
<p>Modules to include in your DevOS shell. the <code>modules</code> argument
will be exported under the <code>devshellModules</code> output</p>
<p><em><em>Type</em></em>:
submodule or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="devshellexportedmodules"><a class="header" href="#devshellexportedmodules">devshell.exportedModules</a></h2>
<p>modules to include in all hosts and export to devshellModules output</p>
<p><em><em>Type</em></em>:
list of valid module or path convertible to its or anything convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="devshellexternalmodules"><a class="header" href="#devshellexternalmodules">devshell.externalModules</a></h2>
<p>The <code>externalModules</code> option has been removed.
Any modules that should be exported should be defined with the <code>exportedModules</code>
option and all other modules should just go into the <code>modules</code> option.</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="devshellmodules"><a class="header" href="#devshellmodules">devshell.modules</a></h2>
<p>modules to include that won't be exported
meant importing modules from external flakes</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="nixos-api-container"><a class="header" href="#nixos-api-container">NixOS API Container</a></h1>
<p>Configure your nixos modules, profiles &amp; suites.</p>
<h2 id="nixos"><a class="header" href="#nixos">nixos</a></h2>
<p>hosts, modules, suites, and profiles for NixOS</p>
<p><em><em>Type</em></em>:
submodule or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="nixoshostdefaults"><a class="header" href="#nixoshostdefaults">nixos.hostDefaults</a></h2>
<p>Defaults for all hosts.
the modules passed under hostDefaults will be exported
to the 'nixosModules' flake output.
They will also be added to all hosts.</p>
<p><em><em>Type</em></em>:
submodule</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="nixoshostdefaultschannelname"><a class="header" href="#nixoshostdefaultschannelname">nixos.hostDefaults.channelName</a></h2>
<p>Channel this host should follow</p>
<p><em><em>Type</em></em>:
channel defined in <code>channels</code></p>
<h2 id="nixoshostdefaultsexportedmodules"><a class="header" href="#nixoshostdefaultsexportedmodules">nixos.hostDefaults.exportedModules</a></h2>
<p>modules to include in all hosts and export to nixosModules output</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="nixoshostdefaultsexternalmodules"><a class="header" href="#nixoshostdefaultsexternalmodules">nixos.hostDefaults.externalModules</a></h2>
<p>The <code>externalModules</code> option has been removed.
Any modules that should be exported should be defined with the <code>exportedModules</code>
option and all other modules should just go into the <code>modules</code> option.</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="nixoshostdefaultsmodules"><a class="header" href="#nixoshostdefaultsmodules">nixos.hostDefaults.modules</a></h2>
<p>modules to include that won't be exported
meant importing modules from external flakes</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="nixoshostdefaultssystem"><a class="header" href="#nixoshostdefaultssystem">nixos.hostDefaults.system</a></h2>
<p>system for this host</p>
<p><em><em>Type</em></em>:
null or system defined in <code>supportedSystems</code></p>
<p><em><em>Default</em></em></p>
<pre><code>null
</code></pre>
<h2 id="nixoshosts"><a class="header" href="#nixoshosts">nixos.hosts</a></h2>
<p>configurations to include in the nixosConfigurations output</p>
<p><em><em>Type</em></em>:
attribute set of submodules</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="nixoshostsnamechannelname"><a class="header" href="#nixoshostsnamechannelname">nixos.hosts.&lt;name&gt;.channelName</a></h2>
<p>Channel this host should follow</p>
<p><em><em>Type</em></em>:
null or channel defined in <code>channels</code></p>
<p><em><em>Default</em></em></p>
<pre><code>null
</code></pre>
<h2 id="nixoshostsnamemodules"><a class="header" href="#nixoshostsnamemodules">nixos.hosts.&lt;name&gt;.modules</a></h2>
<p>modules to include</p>
<p><em><em>Type</em></em>:
list of valid modules or anything convertible to it or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<h2 id="nixoshostsnamesystem"><a class="header" href="#nixoshostsnamesystem">nixos.hosts.&lt;name&gt;.system</a></h2>
<p>system for this host</p>
<p><em><em>Type</em></em>:
null or system defined in <code>supportedSystems</code></p>
<p><em><em>Default</em></em></p>
<pre><code>null
</code></pre>
<h2 id="nixoshostsnametests"><a class="header" href="#nixoshostsnametests">nixos.hosts.&lt;name&gt;.tests</a></h2>
<p>tests to run</p>
<p><em><em>Type</em></em>:
list of valid NixOS test or path convertible to its or anything convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>[]
</code></pre>
<p><em><em>Example</em></em></p>
<pre><code>{"_type":"literalExpression","text":"[\n {\n name = \"testname1\";\n machine = { ... };\n testScript = ''\n # ...\n '';\n }\n ({ corutils, writers, ... }: {\n name = \"testname2\";\n machine = { ... };\n testScript = ''\n # ...\n '';\n })\n ./path/to/test.nix\n];\n"}
</code></pre>
<h2 id="nixosimportables"><a class="header" href="#nixosimportables">nixos.importables</a></h2>
<p>Packages of paths to be passed to modules as <code>specialArgs</code>.</p>
<p><em><em>Type</em></em>:
attribute set</p>
<p><em><em>Default</em></em></p>
<pre><code>{}
</code></pre>
<h2 id="nixosimportablessuites"><a class="header" href="#nixosimportablessuites">nixos.importables.suites</a></h2>
<p>collections of profiles</p>
<p><em><em>Type</em></em>:
null or attribute set of list of paths or anything convertible to its or path convertible to it</p>
<p><em><em>Default</em></em></p>
<pre><code>null
</code></pre>
<div style="break-before: page; page-break-before: always;"></div><h1 id="tldr"><a class="header" href="#tldr">TL;DR;</a></h1>
<ul>
<li><strong>Target Branch</strong>: <code>main</code></li>
<li><strong>Merge Policy</strong>: green check: merge away. yellow circle: have patience. red x: try again.</li>
<li><strong>Docs</strong>: every change set is expected to contain doc updates</li>
<li><strong>Commit Msg</strong>: be a poet! Comprehensive and explanatory commit messages
should cover the motivation and use case in an easily understandable manner
even when read after a few months.</li>
<li><strong>Test Driven Development</strong>: please default to test driven development you can
make use of the <code>./examples</code> &amp; <code>./e2e</code> and wire test up in the devshell.</li>
</ul>
<h3 id="within-the-devshell-nix-develop"><a class="header" href="#within-the-devshell-nix-develop">Within the Devshell (<code>nix develop</code>)</a></h3>
<ul>
<li><strong>Hooks</strong>: please <code>git commit</code> within the devshell</li>
<li><strong>Fail Early</strong>: please run <code>check-all</code> from within the devshell on your local machine</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js"></script>
<script src="mark.min.js"></script>
<script src="searcher.js"></script>
<script src="clipboard.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
<!-- Custom JS scripts -->
<script>
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink