doc: Add system-manager manual mdBook (#206)

* doc: Add system-manager manual mdBook

* Add basic nixos installation steps

* Continue testing for nixos installation

* Add more info regarding nix channel usage

* Add some notes to self

* Add README to manual

* add ad-hoc section, and do some re-arranging

* Add systemd service module example to introduction.md

* wip usage

* add selinux and minimal usage examples

* add remaining manual sections

.treefmt.toml

@@ -7,3 +7,7 @@ includes = ["*.nix"]
 [formatter.rustfmt]
 command = "rustfmt"
 includes = ["*.rs"]
+
+[formatter.markdown]
+command = "mdformat"
+includes = ["*.md"]

README.md

@@ -17,12 +17,10 @@
 
 This project provides a basic method to manage system configuration using [Nix][nixos]
 on any Linux distribution.
-It builds on the many modules that already exist in [NixOS][nixos].
+It builds on the many [modules that already exist in NixOS](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules).
 
 *Warning*: System Manager is a work in progress, you can expect things not to work or to break.
 
-[nixos]: https://nixos.org
-
 ## Usage
 
 ### Install Nix
@@ -39,9 +37,6 @@ to install Nix.
 > for which one you want to install. System Manager is not tested against Determinate Nix.
 > It's recommended to use the official Nix if installing via the Determinate Nix Installer.
 
-[official-installer]: https://nixos.org/download.html
-[detsys-installer]: https://github.com/DeterminateSystems/nix-installer
-
 ## Usage with flakes
 
 ### Defining the configuration
@@ -59,7 +54,7 @@ A basic Nix flake using System Manager would look something like this:
     };
   };
 
-  outputs = { self, flake-utils, nixpkgs, system-manager }: {
+  outputs = { self, nixpkgs, system-manager }: {
     systemConfigs.default = system-manager.lib.makeSystemConfig {
       modules = [
         ./modules
@@ -115,6 +110,7 @@ A simple System Manager module could look something like this:
 ### Activating the configuration
 
 Once the configuration is defined, you can activate it using the `system-manager` CLI:
+
 ```sh
 nix run 'github:numtide/system-manager' -- switch --flake '.'
 ```
@@ -123,11 +119,11 @@ nix run 'github:numtide/system-manager' -- switch --flake '.'
 
 By design flakes run in [pure evaluation mode](https://wiki.nixos.org/wiki/Flakes#Making_your_evaluations_pure).
 In some cases you may not want this. To run an impure evaluation of the flake, add the following option to your command:
+
 ```sh
 --nix-option pure-eval false
 ```
 
-
 ## Currently supported features
 
 Currently it is possible to configure files under `/etc/` and systemd services.
@@ -145,7 +141,7 @@ System Manager is currently only supported on NixOS and Ubuntu. However, it can
 }
 ```
 
-> [!WARNING]
+> \[!WARNING\]
 > This is unsupported and untested. Use at your own risk.
 
 ## Commercial support
@@ -154,3 +150,7 @@ Looking for help or customization?
 
 Get in touch with Numtide to get a quote. We make it easy for companies to
 work with Open Source projects: <https://numtide.com/contact>
+
+[detsys-installer]: https://github.com/DeterminateSystems/nix-installer
+[nixos]: https://nixos.org
+[official-installer]: https://nixos.org/download.html

manual/.gitignore

@@ -0,0 +1 @@
+book

manual/README.md

@@ -0,0 +1,7 @@
+# System Manager Manual
+
+To get started, use the `shell.nix` devShell from the project root with either the `nix develop` or `nix-shell` commands.
+
+This will put `mdbook` on your `$PATH`.
+
+To view the book locally with live reloading, run `mdbook serve manual` from the project root.

manual/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["numtide-contributors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "System Manager Manual"

manual/src/SUMMARY.md

@@ -0,0 +1,22 @@
+# Table of Contents
+
+- [Table of Contents](./SUMMARY.md)
+- [Preface](./preface.md)
+- [Introduction](./introduction.md)
+- [Installation](./installation.md)
+  - [Standalone Installation](./installation/standalone.md)
+  - [NixOS](./installation/nixos.md)
+- [Usage](./usage.md)
+  - [Example Configuration](./usage/example-configuration.md)
+  - [Environment](./usage/environment.md)
+  - [Systemd Services](./usage/systemd-services.md)
+- [Contributing](./contributing.md)
+  - [Extending System Manager](./contributing/extending-system-manager.md)
+- [Troubleshooting](./troubleshooting.md)
+  - [SELinux](./troubleshooting/selinux.md)
+
+<!--
+  TODO:
+  - Building and deploying a configuration to remote machine
+  - Docker guide
+-->

manual/src/contributing.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Welcome! Thank you for interest in the `system-manager` project, your contributions are greatly appreciated.
+
+The following is a general guide for contributing to the project. For guidance on extending `system-manager` to fit specific needs,
+such as adding support for your distribution, or creating a release branch, see the [Extending System Manager](./contributing/extending-system-manager.md) section of the manual.
+
+## Getting Started
+
+> `system-manager` development requires a nix installation with the `flakes` and `nix-command` features enabled. If you do not have nix installed, please refer to the [Installation](./installation.md) section of the manual.
+
+1. Firstly, [create a fork the repository](github.com/numtide/system-manager/fork) where you will make your changes.
+1. Create a copy of your newly created fork on your local machine: `git clone git@github.com:<USER>/system-manager.git`, where `<USER>` is which ever account the fork was created on.
+1. Enter the development environment: `nix develop`. This will supply you with the tool necessary to build and test the repository.
+1. [Create an issue](#creating-issues) for the problem you are trying to solve, if it does not already exist.
+1. [Create a pull request](#creating-pull-requests) that would close the issue.
+
+### Creating Pull Requests
+
+> Important: Please be sure an issue exists for the problem you are trying to fix before opening a pull request.
+
+1. Create a working branch that targets the issue number you would like to close: `git checkout -b <USER>/123`.
+1. Add, commit and push your changes:
+
+```sh
+git add -A
+git commit -m "fix: Fixes ..."
+git push origin <USER>/123
+```
+
+3. [Open a pull request upstream](https://github.com/numtide/system-manager/compare) for your branch targetting the `main` branch.
+1. Please add a few sentences which describe your changes, and use [closing keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) to close the issue your pull request aims to close automatically.
+
+### Creating Issues
+
+Before creating a new issue, please do a [quick search of the existing issues](github.com/numtide/system-manager/issues) to be sure the problem is not already being tracked or worked on by someone else.

manual/src/contributing/extending-system-manager.md

@@ -0,0 +1,70 @@
+# Extending System Manager
+
+## Creating an Ad-Hoc Release
+
+There is currently not a release plan that follows nixpkgs releases, but the following ad-hoc solution is possible. The following guide is a walk-through of
+how to create a release branch for some version of nixpkgs, in this case `nixpkgs-24.05`, which the commit for can be found [here](https://github.com/numtide/system-manager/compare/numtide:64ca98a...numtide:d9cd850).
+
+1. Check that a release branch for the required version does not already exist.
+1. Fork and clone the `system-manager` repository and create a new branch for the release in the following format `release-<TAG>`, for example:
+
+```sh
+git checkout -b release-24.05
+```
+
+3. Update the `nixpkgs` ref in the flake inputs with the new tag:
+
+```diff
+  # system-manager/flake.nix
+  {
+-   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
++   inputs.nixpkgs.url = "github:NixOS/nixpkgs/24.05";
+    # ...
+  }
+```
+
+4. Run `nix flake update nixpkgs`.
+1. Update the `Cargo.toml` package with the appropriate versioning information. The `version` attribute should include the `nixpkgs` tag,
+   and the `rust-version` should be locked at the version of rust which will make the flake checks compile successfully. For `nixpkgs-24.05` that looks like:
+
+```diff
+  # Cargo.toml
+  [package]
+  name = "system_manager"
+- version = "0.1.0"
++ version = "0.1.0+nixpkgs-24.05"
++ rust-version = "1.77"
+```
+
+6. Run `cargo generate-lockfile`.
+1. Ensure the flake checks pass: `nix flake check --keep-going -L`.
+
+> Note that there may be breaking changes between nixpkgs versions which could require additional debugging.
+
+8. Lastly, reference the release branch in your flake:
+
+```diff
+  # your-flake.nix
+  {
+-   inputs.nixpkgs.url = "github:NixOS/nixpkgs/23.11";
++   inputs.nixpkgs.url = "github:NixOS/nixpkgs/24.05";
+    inputs.system-manager = {
+-     url = "github:numtide/system-manager";
++     type = "github";
++     owner = "numtide";
++     repo = "system-manager";
++     ref = "release-24.05";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  }
+```
+
+## Adding New Distributions
+
+> This section assumes you have an existing nix installation. Otherwise, refer to the [Installation](../installation.md) section of the manual for installation instructions.
+
+To add a new distribution, first initialize a new flake repository with `nix run 'github:numtide/system-manager' -- init --flake --allow-any-distro`.
+Once the flake is initialized, switch to the new configuration with `nix run 'github:numtide/system-manager' -- switch --flake '.'`. It is not unlikely
+that this will produce errors, but please refer to the FAQ, github issues, discussion or contributing guide for potential solutions, or instructions for upstreaming changes.
+
+Once the distribution is stable, it can be added to the `supportedIds` list that is part of the [system-manager module](../../../nix/modules/default.nix)'s `config` attribute.

manual/src/installation.md

@@ -0,0 +1,41 @@
+# Installation
+
+## Supported Systems
+
+System Manager is in the early stages of development and while it aims to support any Linux
+distribution, currently official support is limited to the following distributions:
+
+- Ubuntu
+- NixOS
+
+> We would love to expand this list! Please see our [Contributing Guide](./contributing.md)
+> for instructions on how to contribute to `system-manager`.
+
+## [NixOS Installation](./installation/nixos.md)
+
+NixOS is a fully reproducible and immutable Linux distribution based on the Nix package manager that uses an atomic update model.
+
+To install System Manager on NixOS, see [NixOS Installation](./installation/nixos.md).
+
+## Other Distributions
+
+### Install Nix
+
+In order to use System Manager, you will first need to install Nix.
+You can either use your distro's package manager, or use one of the available options
+to install Nix.
+
+- [Official Nix Installer][official-installer] - The canonical source for installing nix.
+- [Determinate Nix Installer][detsys-installer] - A wrapper around the official installer that has SELinux support, and enables flake features by default.
+
+> Note: Be advised that the Determinate Systems installer has the option for the official
+> Nix, as well as Determinate's own variant of Nix (Determinate Nix). It will prompt you
+> for which one you want to install. System Manager is not tested against Determinate Nix.
+> It's recommended to use the official Nix if installing via the Determinate Nix Installer.
+
+### [Install System Manager](./installation/standalone.md)
+
+To install System Manager, please find the instructions for your preferred distribution at [Standalone Installation](./installation/standalone.md).
+
+[detsys-installer]: https://github.com/DeterminateSystems/nix-installer
+[official-installer]: https://nixos.org/download.html

manual/src/installation/nixos.md

@@ -0,0 +1,146 @@
+# NixOS Installation
+
+This section covers how to get `system-manager`, the command line application, on your system.
+Please refer to [Usage](./usage.md) for how to handle creation and application of modules, and management of files.
+
+## Flake Based Configurations
+
+To add `system-manager` to an existing flake based configuration, add the following to the `inputs` field of `flake.nix`.
+
+```nix
+# flake.nix
+{
+  inputs = {
+    system-manager.url = "github:numtide/system-manager";
+  };
+}
+```
+
+<!--
+  @channels
+  Remove after #207 is completed.
+-->
+
+> NOTE: Occassionally the nixpkgs version may be incompatible with the `main` branch of `system-manager`.
+> In such cases, check the current version of nixpkgs in `flake.lock` against `system-manager`.
+> You may need to update the version of nixpkgs in `inputs`, or find the commit at which `system-manager` is supported
+> at that version of nixpkgs and lock `system-manager` at that commit. For instance, the following commit is the only commit
+> that will work for (at least) `nixpkgs-24.05` and below due to changes in Cargo's lock file parsing standard after Rust 1.83
+> became available in nixpkgs:
+>
+> ```nix
+> {
+>   inputs = {
+>     nixpkgs.url = "github:NixOS/nixpkgs/24.05";
+>     system-manager = {
+>       type = "github";
+>       owner = "numtide";
+>       repo = "system-manager";
+>       ref = "64627568a52fd5f4d24ecb504cb33a51ffec086d";
+>     };
+>   };
+> }
+> ```
+>
+> See [Issue #207](https://github.com/numtide/system-manager/issues/207) for progress on alleviating this problem, or [create an ad-hoc release](../contributing/extending-system-manager.md).
+
+The `system-manager` package is available via the flake's `packages` attribute.
+The following is a flake that declares a single NixOS configuration containing a module with the `system-manager`
+package added to the environment.
+
+```nix
+# flake.nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    system-manager = {
+      url = "github:numtide/system-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+  outputs = inputs@{ self }: {
+    let
+      system = "aarch64-linux";
+      host = "nixos";
+    in
+    nixosConfigurations.${host} = inputs.nixpkgs.lib.nixosSystem {
+      inherit system;
+      modules = [
+        ({ config, ... }: {
+          environment.systemPackages = [
+            inputs.system-manager.packages.${system}.system-manager
+          ];
+        })
+      ];
+    };
+  };
+}
+```
+
+Switching to this configuration will install `system-manager`.
+
+```sh
+sudo nixos-rebuild switch --flake ./path/to/flake.nix#nixos
+system-manager --version
+# system_manager 0.1.0
+```
+
+> Note: In this case our host's name is `nixos`, and to reference an attribute we tack on `#` to the flake path, followed by the name of the attribute we want to reference.
+
+## Nix Channels
+
+> _**NOTICE**_: The `system-manager` application currently only supports flakes. Until a release schedule is put in place that can support nix channels, it is advised to follow the guide for [flake based configurations](#flake-based-configurations) instead.
+> If an ad-hoc release is necessary, see [Creating an Ad-Hoc Release](../contributing/extending-system-manager.md).
+
+<!-- This is the NixOS experience without the flake features enabled. You can find which channels you are currently using with `nix-channel --list`. -->
+
+<!-- The configuration that NixOS uses with channels is at `/etc/nixos/configuration.nix`. -->
+
+<!--
+  @channels
+  Remove after #207 is completed.
+-->
+
+<!-- Currently, there isn't a release plan for `system-manager` that is in tandem with nixpkgs releases. This has been an issue -->
+
+<!-- in some cases that have caused failures in [_version mismatches_](https://github.com/numtide/system-manager/issues/172). -->
+
+<!-- The only available archive is the `main` branch, which is pinned to `nixos-unstable`. -->
+
+<!-- If you are currently using the unstable channel already and wish to use channels specifically you could do the following: -->
+
+<!-- ```sh -->
+
+<!-- nix-channel --add https://github.com/numtide/system-manager/archive/main.tar.gz system-manager -->
+
+<!-- nix-channel --update -->
+
+<!-- nix-channel --list -->
+
+<!-- # system-manager https://github.com/numtide/system-manager/archive/main.tar.gz -->
+
+<!-- ``` -->
+
+<!-- TODO: Test this, as I am just speculating that this is possible. -->
+
+<!-- It should then be possible to add the following to `imports` in `/etc/nixos/configuration.nix` and gain access to the [`system-manager` module](../../../nix/modules/default.nix)'s `options` attribute: -->
+
+<!-- ```nix -->
+
+<!-- { pkgs, ... }: { -->
+
+<!-- imports = [ -->
+
+<!-- ``` -->
+
+<!-- <system-manager/nix/modules> -->
+
+<!-- ./hardware-configuration.nix -->
+
+<!-- ``` -->
+
+<!-- ]; -->
+
+<!-- } -->
+
+<!-- ``` -->

manual/src/installation/standalone.md

@@ -0,0 +1,139 @@
+# Standalone Installation
+
+This section covers how to get `system-manager`, the command line application, on your system.
+Please refer to [Usage](./usage.md) for how to handle creation and application of modules, and management of files.
+
+## Flake Based Configurations
+
+To add `system-manager` to an existing flake based configuration, add the following to the `inputs` field of `flake.nix`.
+
+```nix
+# flake.nix
+{
+  inputs = {
+    system-manager.url = "github:numtide/system-manager";
+  };
+}
+```
+
+<!--
+  @channels
+  Remove after #207 is completed.
+-->
+
+> NOTE: Occassionally the nixpkgs version may be incompatible with the `main` branch of `system-manager`.
+> In such cases, check the current version of nixpkgs in `flake.lock` against `system-manager`.
+> You may need to update the version of nixpkgs in `inputs`, or find the commit at which `system-manager` is supported
+> at that version of nixpkgs and lock `system-manager` at that commit. For instance, the following commit is the only commit
+> that will work for (at least) `nixpkgs-24.05` and below due to changes in Cargo's lock file parsing standard after Rust 1.83
+> became available in nixpkgs:
+>
+> ```nix
+> {
+>   inputs = {
+>     nixpkgs.url = "github:NixOS/nixpkgs/24.05";
+>     system-manager = {
+>       type = "github";
+>       owner = "numtide";
+>       repo = "system-manager";
+>       ref = "64627568a52fd5f4d24ecb504cb33a51ffec086d";
+>     };
+>   };
+> }
+> ```
+>
+> See [Issue #207](https://github.com/numtide/system-manager/issues/207) for progress on alleviating this problem, or [create an ad-hoc release](../contributing/extending-system-manager.md).
+
+The `system-manager` package is available via the flake's `packages` attribute.
+The following is a flake that declares a single system configuration containing a module with the `system-manager`
+package added to the environment.
+
+```nix
+# flake.nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    system-manager = {
+      url = "github:numtide/system-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+  outputs = inputs@{ self }: {
+    systemConfigs.ubuntu = inputs.system-manager.lib.makeSystemConfig {
+      modules = [
+        ({
+          config.environment.systemPackages = [
+            inputs.system-manager.packages.${system}.system-manager
+          ];
+        })
+      ];
+    };
+  };
+}
+```
+
+Switching to this configuration will install `system-manager`.
+
+Ensure that `$PATH` state is used when invoking nix via `sudo`, which is required for switching configurations.
+
+```sh
+sudo env PATH="$PATH" nix run 'github:numtide/system-manager' -- switch --flake '.#ubuntu'
+system-manager --version
+# system_manager 0.1.0
+```
+
+> Note: In this case our host's name is `ubuntu`, and to reference an attribute we tack on `#` to the flake path, followed by the name of the attribute we want to reference.
+
+## Nix Channels
+
+> _**NOTICE**_: The `system-manager` application currently only supports flakes. Until a release schedule is put in place that can support nix channels, it is advised to follow the guide for [flake based configurations](#flake-based-configurations) instead.
+> If an ad-hoc release is necessary, see [Creating an Ad-Hoc Release](../contributing/extending-system-manager.md).
+
+<!-- This is the Nix experience without the flake features enabled. You can find which channels you are currently using with `nix-channel --list`. -->
+
+<!--
+  @channels
+  Remove after #207 is completed.
+-->
+
+<!-- Currently, there isn't a release plan for `system-manager` that is in tandem with nixpkgs releases. This has been an issue -->
+
+<!-- in some cases that have caused failures in [_version mismatches_](https://github.com/numtide/system-manager/issues/172). -->
+
+<!-- The only available archive is the `main` branch, which is pinned to `nixos-unstable`. -->
+
+<!-- If you are currently using the unstable channel already and wish to use channels specifically you could do the following: -->
+
+<!-- ```sh -->
+
+<!-- nix-channel --add https://github.com/numtide/system-manager/archive/main.tar.gz system-manager -->
+
+<!-- nix-channel --update -->
+
+<!-- nix-channel --list -->
+
+<!-- # system-manager https://github.com/numtide/system-manager/archive/main.tar.gz -->
+
+<!-- ``` -->
+
+<!-- TODO: Test this, as I am just speculating that this is possible. -->
+
+<!-- It should then be possible to add the following to `imports` in `~/.config/system-manager/system.nix` and gain access to the [`system-manager` module](../../../nix/modules/default.nix)'s `options` attribute: -->
+
+<!-- ```nix -->
+
+<!-- { pkgs, ... }: { -->
+
+<!-- imports = [ -->
+
+<!-- ``` -->
+
+<!-- <system-manager/nix/modules> -->
+
+<!-- ``` -->
+
+<!-- ]; -->
+
+<!-- } -->
+
+<!-- ``` -->

manual/src/introduction.md

@@ -0,0 +1,61 @@
+# Introduction
+
+`system-manager` is a command line tool that uses system configurations written in the nix language
+to manage installation of system services on Linux distributions, such as Ubuntu, in a similar manner to
+`nixos-rebuild` on NixOS systems.
+
+## Hello, System Manager
+
+The following snippet of nix code...
+
+```nix
+{ lib, pkgs, ... }:
+{
+  config.systemd.services.say-hello = {
+    description = "say-hello";
+    enable = true;
+    wantedBy = [ "system-manager.target" ];
+    serviceConfig = {
+      Type = "oneshot";
+      RemainAfterExit = true;
+    };
+    script = ''
+      ${lib.getBin pkgs.hello}/bin/hello
+    '';
+  };
+}
+```
+
+produces a systemd service file, `/etc/systemd/system/say-hello.service`:
+
+```service
+[Unit]
+Description=say-hello
+
+[Service]
+Environment="PATH=..."
+ExecStart=/nix/store/...-unit-script-say-hello-start/bin/say-hello-start
+RemainAfterExit=true
+Type=oneshot
+
+[Install]
+WantedBy=system-manager.target
+```
+
+When the service is enabled it results in `"Hello, World!"` in the journal of the service `say-hello.service`:
+
+```sh
+systemctl status say-hello.service
+● say-hello.service - say-hello
+     Loaded: loaded (/etc/systemd/system/say-hello.service; enabled; vendor preset: enabled)
+     Active: active (exited) since Wed 2025-05-21 09:39:24 PDT; 11min ago
+   Main PID: 41644 (code=exited, status=0/SUCCESS)
+        CPU: 3ms
+
+May 21 09:39:24 ubuntu systemd[1]: Starting say-hello...
+May 21 09:39:24 ubuntu say-hello-start[41646]: Hello, world!
+May 21 09:39:24 ubuntu systemd[1]: Finished say-hello.
+```
+
+> Context omitted for clarity, see [Example Configuration](./usage/example-configuration.md)
+> for a fully functioning use case.

manual/src/preface.md

@@ -0,0 +1,6 @@
+# Preface
+
+This manual contains information on how to install, use and extend `system-manager`.
+
+For questions, please have a look at the discussion board prior to opening a new ticket.
+If you run into a bug or would like to request a feature that is not yet tracked, please [open an issue](https://github.com/numtide/system-manager/issues).

manual/src/troubleshooting.md

@@ -0,0 +1,3 @@
+# Troubleshooting
+
+The following section contains steps to solve common issues. If there is an issue not listed here, please [open an issue](./contributing.md).

manual/src/troubleshooting/selinux.md

@@ -0,0 +1,6 @@
+# SELinux
+
+Currently, `system-manager` does not work with SELinux, but we are working on it! For a trail to follow please see [this issue](https://github.com/numtide/system-manager/issues/115).
+
+The Determinate Systems installer automatically creates a policy for nix itself. Please see the [Installation](../installation.md) section for details.
+This alone will not be enough for `system-manager` to work, but it's a step in the right direction. As of now, the only way for it to work is to set the policy to permissive.

manual/src/usage.md

@@ -0,0 +1,12 @@
+# Usage
+
+The [`system-manager` nix module](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix) currently supports the following `options`:
+
+- management of [`systemd` service modules](./usage/systemd-services.md)
+- management of [system level packages](./usage/environment.md)
+- management of [files and permissions](./usage/environment.md)
+
+> **Note**: Docs can fall out of date. Please refer to the [module itself](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix) for an exhaustive look at what is supported.
+
+If an option you would like to see is not currently supported, please consider [contributing
+to the project](./contributing.md), or open an issue and a maintainer may add support if time allows.

manual/src/usage/environment.md

@@ -0,0 +1,46 @@
+# Managing System Environment
+
+## Adding Packages
+
+Adding packages with `system-manager` works in the same way that it does on `nixos`, the only difference is that the `system-manager` module expects a `config`.
+The list of available config options can be found [here](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix).
+
+Below is a minimal example `system.nix` which can be imported in via `modules` with `makeSystemConfig`.
+
+```nix
+# system.nix
+{ pkgs, ... }:
+{
+  config = {
+    environment.systemPackages = with pkgs; [
+      cowsay
+    ];
+  };
+}
+```
+
+## Managing Files
+
+Managing files in `/etc` with `system-manager` works in the same way that it does on `nixos`, the only difference is that the `system-manager` module expects a `config`.
+The list of available config options can be found [here](https://github.com/numtide/system-manager/blob/main/nix/modules/default.nix).
+
+Below is a minimal example `system.nix` which can be imported in via `modules` with `makeSystemConfig`.
+
+```nix
+# system.nix
+{ ... }:
+{
+  config = {
+    environment.etc = {
+      with_ownership = {
+        text = ''
+          ...
+        '';
+        mode = "0755";
+        uid = 5;
+        gid = 6;
+      };
+    };
+  };
+}
+```

manual/src/usage/example-configuration.md

@@ -0,0 +1,137 @@
+# Example Configuration
+
+This is a minimal example which adds the `system-manager` package to the environment, a simple
+`say-hello` systemd service, and some arbitrary text file to `/etc`. Other examples used in testing
+can be found in the repository's [examples](https://github.com/numtide/system-manager/tree/main/examples) directory.
+
+First, we create a `system.nix` module, which will be the base configuration for our system.
+
+```nix
+{ lib, pkgs, ... }:
+{
+  config = {
+    nixpkgs.hostPlatform = "aarch64-linux";
+
+    environment = {
+      # Packages that should be installed
+      # on a system
+      systemPackages = with pkgs; [
+        git
+        nil
+        helix
+      ];
+
+      # Add directories and files to `/etc`
+      # and set their permissions
+      etc = {
+        my_text_file = {
+          text = ''
+            Arbitrary text file content.
+          '';
+        };
+      };
+    };
+
+    # Create systemd services
+    systemd.services.say-hello = {
+      description = "say-hello";
+      enable = true;
+      wantedBy = [ "system-manager.target" ];
+      serviceConfig = {
+        Type = "oneshot";
+        RemainAfterExit = true;
+      };
+      script = ''
+        ${lib.getBin pkgs.hello}/bin/hello
+      '';
+    };
+
+    # Configure systemd services
+    services.say-hello.enable = true;
+  };
+}
+```
+
+Then we can reference the file path in our flake. For simplicity's sake, we include another
+attribute set in `modules` which captures the `system-manager` package as part of the system's
+`environment.systemPackages`.
+
+> Because nix is a functional configuration language, this is cumulative
+> and the resulting system will include both the `systemPackages` from our `system.nix` as well as
+> any other modules we include which refer to `environment.systemPackages`.
+
+```nix
+{
+  description = "Example System Manager configuration.";
+
+  inputs = {
+    # Specify the source of System Manager and Nixpkgs.
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    system-manager = {
+      url = "github:numtide/system-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      system-manager,
+      ...
+    }:
+    {
+      systemConfigs.default = system-manager.lib.makeSystemConfig {
+        # Specify your system configuration modules here, for example,
+        # the path to your `system.nix`.
+        modules = [
+          ./system.nix
+          ({
+            config.environment.systemPackages = [
+              system-manager.packages.${system}.system-manager
+            ];
+          })
+        ];
+      };
+    };
+}
+```
+
+Now that we have a system configuration that `system-manager` can build, we build and switch
+to the configuration in one step:
+
+Ensure that `$PATH` state is used when invoking nix via `sudo`, which is required for switching configurations.
+
+```sh
+sudo env PATH="$PATH" nix run 'github:numtide/system-manager' -- switch --flake '.#ubuntu'
+```
+
+Once the command finishes, the following commands should yeild their expected output:
+
+```sh
+system-manager --version
+system-manager 0.1.0
+
+git --version
+git 2.49.0
+
+nil --version
+nil 2024-08-06
+
+hx --version
+helix 25.01.1 (e7ac2fcd)
+
+cat /etc/my_text_file
+Arbitrary text file content.
+
+systemctl status say-hello.service
+● say-hello.service - say-hello
+     Loaded: loaded (/etc/systemd/system/say-hello.service; enabled; vendor preset: enabled)
+     Active: active (exited) since Wed 2025-05-21 09:39:24 PDT; 11min ago
+   Main PID: 41644 (code=exited, status=0/SUCCESS)
+        CPU: 3ms
+
+May 21 09:39:24 ubuntu systemd[1]: Starting say-hello...
+May 21 09:39:24 ubuntu say-hello-start[41646]: Hello, world!
+May 21 09:39:24 ubuntu systemd[1]: Finished say-hello.
+```

manual/src/usage/systemd-services.md

@@ -0,0 +1,41 @@
+# Managing Systemd Service Modules
+
+Custom or existing systemd services can be created and configured with `system-manager`.
+This topic is relative to `system-manager`, and is more directly correlated with `systemd`
+and `nix`. Since it requires knowledge of both we cover it minimally here, however, the
+following resources are a better reference for creating services with nix which can be
+used by the `system-manager` module.
+
+- [Official `systemd.service` docs](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html)
+- [Systemd NixOS Wiki](https://wiki.nixos.org/wiki/Systemd)
+- [Search Engine for NixOS configuration options](https://mynixos.com/search?q=systemd) -- helpful for quickly finding attribute bindings for systemd
+
+## Example systemd module
+
+The following is a simple systemd timer which continues to capture timestamps into a log file
+once every minute, after the timer unit itself is activated.
+
+Further configurations settings for creating a `systemd.timer` can be found in the [official `systemd.timer` docs](https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html).
+
+```nix
+{ pkgs, ... }:
+{
+  systemd = {
+    timers.simple-timer = {
+      wantedBy = [ "timers.target" ];
+      timerConfig = {
+        OnActiveSec = "10"; # Defines a timer relative to the moment the timer unit itself is activated.
+        OnCalendar = "minutely";
+        Unit = "simple-timer.service";
+        Persistent = true; # Stores the last activated time to disk.
+      };
+    };
+    services.simple-timer = {
+      serviceConfig.Type = "oneshot";
+      script = ''
+        echo "Time: $(date)." >> /tmp/simple-timer.log
+      '';
+    };
+  };
+}
+```

shell.nix

@@ -38,5 +38,7 @@ pkgs.mkShellNoCC {
     nixfmt-rfc-style
     rustfmt
     clippy
+    mdbook
+    mdformat
   ];
 }