divnix/digga
1
1
Fork 0
mirror of https://github.com/divnix/digga.git synced 2024-12-23 16:11:51 +03:00
Code Issues Projects Releases Wiki Activity
4f18b6b2ce
digga/print.html
nrdxp 4f18b6b2ce deploy: afedb536cc
2021-02-26 07:18:35 +00:00

926 lines
48 KiB
HTML
Raw Blame History

<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>devos docs</title>
<meta name="robots" content="noindex" />
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<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>
<!-- Provide site root to javascript -->
<script type="text/javascript">
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 type="text/javascript">
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 type="text/javascript">
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('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.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="doc/start/index.html"><strong aria-hidden="true">2.</strong> Quick Start</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="doc/start/iso.html"><strong aria-hidden="true">2.1.</strong> ISO</a></li><li class="chapter-item expanded "><a href="doc/start/from-nixos.html"><strong aria-hidden="true">2.2.</strong> From NixOS</a></li></ol></li><li class="chapter-item expanded "><a href="doc/layout.html"><strong aria-hidden="true">3.</strong> Layout</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cachix/index.html"><strong aria-hidden="true">3.1.</strong> Cachix</a></li><li class="chapter-item expanded "><a href="extern/index.html"><strong aria-hidden="true">3.2.</strong> Extern</a></li><li class="chapter-item expanded "><a href="hosts/index.html"><strong aria-hidden="true">3.3.</strong> Hosts</a></li><li class="chapter-item expanded "><a href="modules/index.html"><strong aria-hidden="true">3.4.</strong> Modules</a></li><li class="chapter-item expanded "><a href="overlays/index.html"><strong aria-hidden="true">3.5.</strong> Overlays</a></li><li class="chapter-item expanded "><a href="overrides/index.html"><strong aria-hidden="true">3.6.</strong> Overrides</a></li><li class="chapter-item expanded "><a href="pkgs/index.html"><strong aria-hidden="true">3.7.</strong> Packages</a></li><li class="chapter-item expanded "><a href="profiles/index.html"><strong aria-hidden="true">3.8.</strong> Profiles</a></li><li class="chapter-item expanded "><a href="secrets/index.html"><strong aria-hidden="true">3.9.</strong> Secrets</a></li><li class="chapter-item expanded "><a href="suites/index.html"><strong aria-hidden="true">3.10.</strong> Suites</a></li><li class="chapter-item expanded "><a href="users/index.html"><strong aria-hidden="true">3.11.</strong> Users</a></li></ol></li><li class="chapter-item expanded "><a href="doc/flk/index.html"><strong aria-hidden="true">4.</strong> flk</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="doc/flk/up.html"><strong aria-hidden="true">4.1.</strong> up</a></li><li class="chapter-item expanded "><a href="doc/flk/update.html"><strong aria-hidden="true">4.2.</strong> update</a></li><li class="chapter-item expanded "><a href="doc/flk/get.html"><strong aria-hidden="true">4.3.</strong> get</a></li><li class="chapter-item expanded "><a href="doc/flk/iso.html"><strong aria-hidden="true">4.4.</strong> iso</a></li><li class="chapter-item expanded "><a href="doc/flk/install.html"><strong aria-hidden="true">4.5.</strong> install</a></li><li class="chapter-item expanded "><a href="doc/flk/home.html"><strong aria-hidden="true">4.6.</strong> home</a></li></ol></li><li class="chapter-item expanded "><a href="doc/integrations/index.html"><strong aria-hidden="true">5.</strong> Integrations</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="doc/integrations/deploy.html"><strong aria-hidden="true">5.1.</strong> deploy-rs</a></li><li class="chapter-item expanded "><a href="doc/integrations/hercules.html"><strong aria-hidden="true">5.2.</strong> hercules-ci</a></li></ol></li><li class="chapter-item expanded "><a href="doc/index.html"><strong aria-hidden="true">6.</strong> Contributing</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<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 bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<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 (default)</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">devos 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" name="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 type="text/javascript">
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://hercules-ci.com/github/divnix/devos/jobs"><img src="https://img.shields.io/github/checks-status/divnix/devos/core" alt="Build" /></a>
<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-v20.09-blue.svg?style=flat&amp;logo=NixOS&amp;logoColor=white" alt="NixOS 20.09" /></a></p>
<blockquote>
<h4 id="-advisory-"><a class="header" href="#-advisory-">⚠ Advisory ⚠</a></h4>
<p>DevOS leverages the <a href="https://nixos.wiki/wiki/Flakes">flakes</a> feature available via an <em>experimental</em>
branch of <a href="https://nixos.org/manual/nix/stable">nix</a>. Until nix 3.0 is released, this project should be
considered unstable, though quite usable as flakes have been maturing
<em>well</em>
<a href="https://github.com/divnix/devos/tree/17713c22d07c54525c728c62060a0428b76dee3b">for a while</a>.</p>
</blockquote>
<h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
<p>DevOS grants a simple way to use, deploy and manage <a href="https://nixos.org/manual/nixos/stable">NixOS</a> systems for
personal and productive use. It does this by providing a convenient repository
structure, integrating several popular projects like
<a href="https://nix-community.github.io/home-manager">home-manager</a>, and <a href="https://github.com/numtide/devshell">devshell</a>, and offering useful
conveniences like
<a href="./pkgs#automatic-source-updates">automatic source updates</a>.</p>
<p>Skip the indeterminate nature of other systems, <em>and</em> the perceived difficulty
of Nix. It's easier than you think!</p>
<h2 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h2>
<p>Check out the <a href="https://devos.divnix.com/doc/start">guide</a> to get up and running.</p>
<h2 id="in-the-wild"><a class="header" href="#in-the-wild">In the Wild</a></h2>
<p>You author maintains his own branch, so you can take inspiration, direction, or
make critical comments about my bad <a href="https://github.com/nrdxp/devos/tree/nrd">code</a>. 😜</p>
<h2 id="motivation"><a class="header" href="#motivation">Motivation</a></h2>
<p>NixOS provides an amazing abstraction to manage our environment, but that new
power can sometimes bring feelings of overwhelm and confusion. Having a turing
complete system can easily lead to unlimited complexity if we do it wrong.
Instead, we should have a community consensus on how to manage a NixOS system.</p>
<h2 id="upstream"><a class="header" href="#upstream">Upstream</a></h2>
<p>I'd love to see this in the nix-community should anyone believe its reached a
point of maturity to be generally useful, but I'm all for waiting until
1.0<a href="https://github.com/divnix/devos/issues/121">#121</a> to save the cache work,
too.</p>
<p><em><strong>The future is declarative! 🎉</strong></em></p>
<h2 id="community-profiles"><a class="header" href="#community-profiles">Community Profiles</a></h2>
<p>There are two branches from which to choose: <a href="https://github.com/divnix/devos">core</a> and
<a href="https://github.com/divnix/devos/tree/community">community</a>. The community branch builds on core and includes
several ready-made profiles for discretionary use.</p>
<p>Every package and NixOS profile declared in community is uploaded to
<a href="./cachix">cachix</a>, so everything provided is available without building
anything. This is especially useful for the packages that are
<a href="./overrides">overridden</a> from master, as without the cache, rebuilds are
quite frequent.</p>
<h2 id="inspiration--art"><a class="header" href="#inspiration--art">Inspiration &amp; Art</a></h2>
<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="license"><a class="header" href="#license">License</a></h1>
<p>DevOS is licensed under the <a href="https://mit-license.org">MIT License</a>.</p>
<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>Here is a snippet that will get you the template without the git history:</p>
<pre><code class="language-sh">nix-shell -p cachix --run cachix use nrdxp
nix-shell https://github.com/divnix/devos/archive/core.tar.gz -A shell \
--run &quot;flk get core&quot;
cd flk
nix-shell
git init
git add .
git commit -m init
</code></pre>
<p>This will place you in a new folder named <code>flk</code> with git initialized, and a
nix-shell that provides all the dependencies, including the unstable nix
version required.</p>
<p>In addition, the <a href="doc/start/../../cachix">binary cache</a> is added for faster deployment.</p>
<blockquote>
<h5 id="notes"><a class="header" href="#notes"><em>Notes:</em></a></h5>
<ul>
<li>You can change <code>core</code> to <a href="doc/start/../../index.html#community-profiles"><code>community</code></a>
in the call to <code>flk get</code></li>
<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>
</ul>
</blockquote>
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps:</a></h2>
<ul>
<li><a href="doc/start/./iso.html">Make installable ISO</a></li>
<li><a href="doc/start/./from-nixos.html">Already on NixOS</a></li>
</ul>
<h1 id="iso"><a class="header" href="#iso">ISO</a></h1>
<p>Making and writing an installable iso for <code>hosts/NixOS.nix</code> is as simple as:</p>
<pre><code class="language-sh">flk iso NixOS
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
status=progress oflag=sync
</code></pre>
<p>This works for any file matching <code>hosts/*.nix</code> excluding <code>default.nix</code>.</p>
<h1 id="from-nixos"><a class="header" href="#from-nixos">From NixOS</a></h1>
<h2 id="generate-configuration"><a class="header" href="#generate-configuration">Generate Configuration</a></h2>
<p>Assuming your happy with your existing partition layout, you can generate a
basic NixOS configuration for your system using:</p>
<pre><code class="language-sh">flk up
</code></pre>
<p>This will make a new file <code>hosts/up-$(hostname).nix</code>, which you can edit to
your liking.</p>
<p>Make sure your <code>i18n.defaultLocale</code> and <code>time.timeZone</code> are set properly for
your region. Keep in mind that <code>networking.hostName</code> with be automatically
set to the filename of your hosts file, so <code>hosts/my-host.nix</code> will have the
hostname <code>my-host</code>.</p>
<p>Now might be a good time to read the docs on <a href="doc/start/../../suites">suites</a> and
<a href="doc/start/../../profiles">profiles</a> and add or create any that you need.</p>
<blockquote>
<h5 id="note"><a class="header" href="#note"><em>Note:</em></a></h5>
<p>While the <code>up</code> sub-command is provided as a convenience to quickly set up and
install a &quot;fresh&quot; NixOS system on current hardware, committing these files is
discouraged.</p>
<p>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.</p>
</blockquote>
<h1 id="installation"><a class="header" href="#installation">Installation</a></h1>
<p>Once your ready to deploy <code>hosts/my-host.nix</code>:</p>
<pre><code class="language-sh">flk my-host switch
</code></pre>
<p>This calls <code>nixos-rebuild</code> with sudo to build and install your configuration.</p>
<blockquote>
<h5 id="notes-1"><a class="header" href="#notes-1"><em>Notes:</em></a></h5>
<ul>
<li>
<p>Instead of <code>switch</code>, you can pass <code>build</code>, <code>test</code>, <code>boot</code>, etc just as with
<code>nixos-rebuild</code>.</p>
</li>
<li>
<p>It is convenient to have the template living at <code>/etc/nixos</code> so you can
simply <code>sudo nixos-rebuild switch</code> from anywhere on the system, but it is
not required.</p>
</li>
</ul>
</blockquote>
<h1 id="layout"><a class="header" href="#layout">Layout</a></h1>
<p>Each of the following sections is a directory in the root of the project
serving a singular purpose. Select a chapter to read more about its purpose
and usage.</p>
<h1 id="cachix"><a class="header" href="#cachix">Cachix</a></h1>
<p>The cachix directory simple captures the output of <code>sudo cachix use</code> for the
developers personal cache, as well as the nix-community cache. You can easily
add your own cache, assuming the template lives in /etc/nixos, by simply
running <code>sudo cachix use yourcache</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 divnix</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>
<h1 id="external-art"><a class="header" href="#external-art">External Art</a></h1>
<p>When you need to use a module, overlay, or pass a value from one of your inputs
to the rest of your NixOS configuration, <a href="https://github.com/divnix/devos/tree/core/extern/default.nix">extern</a> is where you do it.</p>
<p>Modules and overlays are self explanatory, and the <code>specialArgs</code> attribute is
used to extend the arguments passed to all NixOS modules, allowing for
arbitrary values to be passed from flake inputs to the rest of your
configuration.</p>
<h2 id="home-manager"><a class="header" href="#home-manager">Home Manager</a></h2>
<p>There is also an <code>hmModules</code> attribute set for pulling home-manager modules in
from the outside world:</p>
<h3 id="declare"><a class="header" href="#declare">Declare:</a></h3>
<p>flake.nix:</p>
<pre><code class="language-nix">{
inputs.doom-emacs.url = &quot;github:vlaci/nix-doom-emacs&quot;;
}
</code></pre>
<p>extern/default.nix:</p>
<pre><code class="language-nix">with inputs;
{
hmModules = {
doom-emacs = doom-emacs.hmModule;
};
}
</code></pre>
<h3 id="use"><a class="header" href="#use">Use:</a></h3>
<p>users/nixos/default.nix:</p>
<pre><code class="language-nix">{ hmModules, ... }:
{
home-manager.users.nixos = {
imports = [ hmModules.doom-emacs ] ;
programs.doom-emacs.enable = true;
};
}
</code></pre>
<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> 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 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>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="hosts/../profiles">profile modules</a>.</p>
<p>This is a good place to import sets of profiles, called <a href="hosts/../suites">suites</a>,
that you intend to use on your machine.</p>
<p>Additionally, this is the perfect place to import anything you might need from
the <a href="https://github.com/NixOS/nixos-hardware">nixos-hardware</a> repository.</p>
<h2 id="example"><a class="header" href="#example">Example</a></h2>
<p>hosts/librem.nix:</p>
<pre><code class="language-nix">{ suites, hardware, ... }:
{
imports = suites.laptop ++ [ hardware.purism-librem-13v3 ];
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;
fileSystems.&quot;/&quot; = { device = &quot;/dev/disk/by-label/nixos&quot;; };
}
</code></pre>
<h1 id="modules"><a class="header" href="#modules">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="modules/../hosts">hosts</a>.</p>
<blockquote>
<h5 id="note-1"><a class="header" href="#note-1"><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="modules/../profiles">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 &quot;Description of my new service.&quot;;
# 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"><a class="header" href="#usage">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 = &quot;...&quot;;
modules = [
devos.nixosModules.my-service
({ ... }: {
services.MyService.enable = true;
})
];
};
};
}
</code></pre>
<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="overlays/../hosts">hosts</a>, and
exported via <code>overlays.&lt;file-basename&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-1"><a class="header" href="#example-1">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>
<h1 id="overrides"><a class="header" href="#overrides">Overrides</a></h1>
<p>By default, the NixOS systems are based on the latest release. While it is
trivial to change this to nixos-unstable or any other branch of nixpkgs by
changing the flake url, sometimes all we want is a single package from another
branch.</p>
<p>This is what the overrides are for. By default, they are pulled directly from
nixpkgs/master, but you can change the <code>override</code> flake input url to
nixos-unstable, or even a specific sha revision.</p>
<h2 id="example-2"><a class="header" href="#example-2">Example</a></h2>
<h3 id="packages"><a class="header" href="#packages">Packages</a></h3>
<p>The override packages are defined as a regular overlay with an extra arguement
<code>pkgs</code>. This refers to the packages built from the <code>override</code> flake.</p>
<p>Pulling the manix package from the override flake:</p>
<pre><code class="language-nix">{
packages = pkgs: final: prev: {
inherit (pkgs) manix;
};
}
</code></pre>
<h3 id="modules-1"><a class="header" href="#modules-1">Modules</a></h3>
<p>You can also pull modules from override. Simply specify their path relative to
the nixpkgs <a href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">modules</a> directory. The old version will be added
to <code>disabledModules</code> and the new version imported into the configuration.</p>
<p>Pulling the zsh module from the override flake:</p>
<pre><code class="language-nix">{
modules = [ &quot;programs/zsh/zsh.nix&quot; ];
}
</code></pre>
<blockquote>
<h5 id="note-2"><a class="header" href="#note-2"><em>Note:</em></a></h5>
<p>Sometimes a modules name will change from one branch to another. This is what
the <code>disabledModules</code> list is for. If the module name changes, the old
version will not automatically be disabled, so simply put it's old name in
this list to disable it.</p>
</blockquote>
<h1 id="packages-1"><a class="header" href="#packages-1">Packages</a></h1>
<p>Similar to <a href="pkgs/../modules">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>This overlay is set as the default <code>overlay</code> output attribute for the flake.
And 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="pkgs/../hosts">host</a>.</p>
<h2 id="automatic-source-updates"><a class="header" href="#automatic-source-updates">Automatic Source Updates</a></h2>
<p>There is the added, but optional, convenience of declaring your sources in
<em>pkgs/flake.nix</em> as an input. This allows updates to be managed automatically
by simply <a href="pkgs/../doc/flk/update.html#updating-package-sources">updating</a> the lock
file. No more manually entering sha256 hashes!</p>
<h2 id="example-3"><a class="header" href="#example-3">Example</a></h2>
<p>pkgs/development/libraries/libinih/default.nix:</p>
<pre><code class="language-nix">{ stdenv, meson, ninja, lib, srcs, ... }:
let version = &quot;r53&quot;;
in
stdenv.mkDerivation {
pname = &quot;libinih&quot;;
inherit version;
src = srcs.libinih;
buildInputs = [ meson ninja ];
mesonFlags = ''
-Ddefault_library=shared
-Ddistro_install=true
'';
meta = with lib; {
description = &quot;Simple .INI file parser in C&quot;;
homepage = &quot;https://github.com/benhoyt/inih&quot;;
maintainers = [ maintainers.divnix ];
license = licenses.bsd3;
platforms = platforms.all;
inherit version;
};
}
</code></pre>
<p>pkgs/default.nix:</p>
<pre><code class="language-nix">final: prev: {
libinih = prev.callPackage ./development/libraries/libinih { };
}
</code></pre>
<p>pkgs/flake.nix:</p>
<pre><code class="language-nix">{
description = &quot;Package sources&quot;;
inputs = {
libinih.url = &quot;github:benhoyt/inih/r53&quot;;
libinih.flake = false;
};
}
</code></pre>
<h1 id="profiles"><a class="header" href="#profiles">Profiles</a></h1>
<p>Profiles are simply NixOS modules which contain generic expressions suitable
for any host. A good example is the configuration for a text editor, or
window manager. If you need some concrete examples, just checkout the
community <a href="https://github.com/divnix/devos/tree/community/profiles">branch</a>.</p>
<h2 id="constraints"><a class="header" href="#constraints">Constraints</a></h2>
<p>For the sake of consistency, a profile should always be defined in a
<em>default.nix</em> containing a valid <a href="https://nixos.wiki/wiki/Module">nixos module</a>
which <em><strong>does not</strong></em> declare any new
<a href="https://nixos.org/manual/nixos/stable/index.html#sec-option-declarations">module options</a>.
If you need to do that, use the <a href="profiles/../modules">modules directory</a>.</p>
<blockquote>
<h5 id="note-3"><a class="header" href="#note-3"><em>Note:</em></a></h5>
<p><a href="profiles/../doc/integrations/hercules.html">hercules-ci</a> expects all profiles to be
defined in a <em>default.nix</em>. Similarly, <a href="profiles/../suites">suites</a> expect a
<em>default.nix</em> as well.</p>
</blockquote>
<h3 id="example-4"><a class="header" href="#example-4">Example</a></h3>
<h4 id="correct-"><a class="header" href="#correct-">Correct ✔</a></h4>
<p>profiles/develop/default.nix:</p>
<pre><code class="language-nix">{ ... }:
{
programs.zsh.enable = true;
}
</code></pre>
<h4 id="incorrect-"><a class="header" href="#incorrect-">Incorrect ❌</a></h4>
<p>profiles/develop.nix:</p>
<pre><code class="language-nix">{
options = {};
}
</code></pre>
<h2 id="subprofiles"><a class="header" href="#subprofiles">Subprofiles</a></h2>
<p>Profiles can also define subprofiles. They follow the same constraints outlined
above. A good top level profile should be a high level concern, such a your
personal development environment, and the subprofiles should be more concrete
program configurations such as your text editor, and shell configs. This way,
you can either pull in the whole development profile, or pick and choose
individual programs.</p>
<h3 id="example-5"><a class="header" href="#example-5">Example</a></h3>
<p>profiles/develop/default.nix:</p>
<pre><code class="language-nix">{
imports = [ ./zsh ];
# some generic development concerns ...
}
</code></pre>
<p>profiles/develop/zsh/default.nix:</p>
<pre><code class="language-nix">{ ... }:
{
programs.zsh.enable = true;
# zsh specific options ...
}
</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
while minimizing boilerplate. Always strive to keep your profiles as generic
and modular as possible. Anything machine specific belongs in your
<a href="profiles/../hosts">host</a> files.</p>
<h1 id="secrets"><a class="header" href="#secrets">Secrets</a></h1>
<p>Secrets are managed using <a href="https://github.com/AGWA/git-crypt">git-crypt</a> so you can keep your flake in
a public repository like GitHub without exposing your password or other
sensitive data.</p>
<p>By default, everything in the secrets folder is automatically encrypted. Just
be sure to run <code>git-crypt init</code> before putting anything in here.</p>
<blockquote>
<h5 id="note-4"><a class="header" href="#note-4"><em>Note:</em></a></h5>
<p>Currently, there is <a href="https://github.com/NixOS/nix/issues/8">no mechanism</a> in nix to deploy secrets
within the nix/store so, if they end up in the nix/store after deployment, they
will be world readable on that machine.</p>
<p>The author of devos intends to implement a workaround for this situation in
the near future, but for the time being, simple be aware of this.</p>
</blockquote>
<h1 id="suites"><a class="header" href="#suites">Suites</a></h1>
<p>Suites provide a mechanism for users to easily combine and name collecitons of
profiles. For good examples, check out the suites defined in the community
<a href="https://github.com/divnix/devos/blob/community/suites/default.nix">branch</a>.</p>
<p>In the future, we will use suites as a mechanism for deploying various machine
types which don't depend on hardware, such as vm's and containers.</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>
<h1 id="users"><a class="header" href="#users">Users</a></h1>
<p>Users are a special case of <a href="users/../profiles">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. For a fully fleshed out example, check out the developers personal
<a href="https://github.com/divnix/devos/tree/nrd/users/nrd/default.nix">branch</a>.</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="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>hmActivations</code> meta-package defined in the flakes <code>legacyPackages</code>
output. The <a href="users/../doc/flk">flk</a> helper script makes this even easier.</p>
<p>This is great for keeping your environment consistent across Unix systems,
including OSX.</p>
<h3 id="from-within-the-projects-devshell"><a class="header" href="#from-within-the-projects-devshell">From within the projects devshell:</a></h3>
<pre><code class="language-sh"># builds the nixos user defined in the NixOS host
flk home NixOS nixos
# build and activate
flk home NixOS nixos switch
</code></pre>
<h3 id="manually-from-outside-the-project"><a class="header" href="#manually-from-outside-the-project">Manually from outside the project:</a></h3>
<pre><code class="language-sh"># build
nix build &quot;github:divnix/devos#hmActivationPackages.NixOS.nixos&quot;
# activate
./result/activate &amp;&amp; unlink result
</code></pre>
<h1 id="flk-command"><a class="header" href="#flk-command">flk command</a></h1>
<p>The devshell for the project incudes a convenient script for managing your
system called <code>flk</code>. Each of the following chapters is a reference for one of
its subcommands.</p>
<h2 id="rebuild"><a class="header" href="#rebuild">Rebuild</a></h2>
<p>Without any of the subcommands, <code>flk</code> acts as a convenient shortcut for
<code>nixos-rebuild</code>:</p>
<pre><code class="language-sh">flk NixOS build
</code></pre>
<p>Will build <em>hosts/NixOS.nix</em>. You can change out <code>build</code> for <code>switch</code>, <code>test</code>,
etc. Any additional arguments are passed through to the call to
<code>nixos-rebuild</code>.</p>
<h2 id="usage-2"><a class="header" href="#usage-2">Usage</a></h2>
<pre><code class="language-sh">flk help
</code></pre>
<h1 id="up"><a class="header" href="#up">up</a></h1>
<p>The <code>up</code> subcommand is a simple shortcut for <code>nixos-generate-config</code> that is
compatible with devos. There is a short explanation in the the getting started
<a href="doc/flk/../start/from-nixos.html#generate-configuration">guide</a>.</p>
<h1 id="update"><a class="header" href="#update">update</a></h1>
<p>The <code>update</code> subcommand is a simple alias for:</p>
<pre><code class="language-sh">nix flake update --recreate-lock-file --commit-lock-file
</code></pre>
<p>As it sounds, this will update your lock file, and commit it.</p>
<h2 id="updating-package-sources"><a class="header" href="#updating-package-sources">Updating Package Sources</a></h2>
<p>If you pass an input name then it will only update that input.</p>
<p>For example, you can update any
<a href="doc/flk/../../pkgs#automatic-source-updates">package sources</a> you may have declared
in <em>pkgs/flake.nix</em>:</p>
<pre><code class="language-sh">flk update srcs
</code></pre>
<h1 id="get"><a class="header" href="#get">get</a></h1>
<p>The <code>get</code> subcommand is useful for getting a bare copy of devos without the
git history. You can pull either the core or community branches.</p>
<h2 id="usage-3"><a class="header" href="#usage-3">Usage</a></h2>
<pre><code class="language-sh">flk get BRANCH DEST-DIR
</code></pre>
<p>If DEST-DIR is ommitted, it defaults to <em>./flk</em>.</p>
<h1 id="iso-1"><a class="header" href="#iso-1">ISO</a></h1>
<p>Making and writing an installable iso for <code>hosts/NixOS.nix</code> is as simple as:</p>
<pre><code class="language-sh">flk iso NixOS
dd bs=4M if=result/iso/*.iso of=/dev/$your_installation_device \
status=progress oflag=sync
</code></pre>
<p>This works for any file matching <code>hosts/*.nix</code> excluding <code>default.nix</code>.</p>
<h1 id="install"><a class="header" href="#install">install</a></h1>
<p>The <code>install</code> subcommand is a simple convenience for <code>nixos-install</code>, similar
to the shortcut for <code>nixos-rebuild</code>, all additional arguments are passed
through.</p>
<h2 id="example-6"><a class="header" href="#example-6">Example</a></h2>
<pre><code class="language-sh">flk install NixOS
</code></pre>
<p>This will install <em>hosts/NixOS.nix</em> to /mnt. You can override this directory
using standard <code>nixos-install</code> args.</p>
<h1 id="home"><a class="header" href="#home">home</a></h1>
<p>The <code>home</code> 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.</p>
<h2 id="usage-4"><a class="header" href="#usage-4">Usage</a></h2>
<p>The <a href="doc/flk/../../users/index.html#external-usage">users</a> page contains a good usage
example.</p>
<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>
<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="doc/integrations/../../hosts">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-5"><a class="header" href="#usage-5">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 = &quot;yes&quot;; };
};
};
}
}
</code></pre>
<p>And run the deployment:</p>
<pre><code class="language-sh">deploy &quot;flk#hostName&quot; --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 sudo access</p>
</blockquote>
<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"><a class="header" href="#setup">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>nix/ci.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-6"><a class="header" href="#note-6"><em>Note:</em></a></h5>
<p>Hercules doesn't have access to anything encrypted in the
<a href="doc/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>
<h1 id="pull-requests"><a class="header" href="#pull-requests">Pull Requests</a></h1>
<p>If making a change to core, 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 <a href="https://devos.divnix.com">mdbook</a>. The book is
rendered on every change, so the docs should always be up to date.</p>
<h2 id="community-prs"><a class="header" href="#community-prs">Community PRs</a></h2>
<p>While much of your work in this template may be idiosyncratic in nature. Anything
that might be generally useful to the broader NixOS community can be synced to
the <code>community</code> branch to provide a host of useful NixOS configurations available
&quot;out of the box&quot;.</p>
<h1 id="style"><a class="header" href="#style">Style</a></h1>
<p>If you wish to contribute please follow these guidelines:</p>
<ul>
<li>
<p>format your code with <a href="https://github.com/nix-community/nixpkgs-fmt"><code>nixpkgs-fmt</code></a>. The default devshell
includes a pre-commit hook that does this for you.</p>
</li>
<li>
<p>The commit message follows the same semantics as <a href="https://github.com/NixOS/nixpkgs">nixpkgs</a>.</p>
<ul>
<li>You can use a <code>#</code> symbol to specify ambiguities. For example,
<code>develop#zsh: &lt;rest of commit message&gt;</code> would tell me that your updating the
<code>zsh</code> subprofile living under the <code>develop</code> profile.</li>
</ul>
</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 type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript">
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink