holy moly we're almost there

doc/integrations/cachix.md

@@ -0,0 +1,17 @@
+# Cachix
+The system will automatically pull a cachix.nix at the root if one exists.
+This is usually created automatically by a `sudo cachix use`. If you're more
+inclined to keep the root clean, you can drop any generated files in the
+`cachix` directory into the `profiles/cachix` directory without further
+modification.
+
+For example, to add your own cache, assuming the template lives in /etc/nixos,
+by simply running `sudo cachix use yourcache`. Then, optionally, move
+`cachix/yourcache.nix` to `profiles/cachix/yourcache.nix`
+
+These caches are only added to the system after a `nixos-rebuild switch`, so it
+is recommended to call `cachix use nrdxp` before the initial deployment, as it
+will save a lot of build time.
+
+In the future, users will be able to skip this step once the ability to define
+the nix.conf within the flake is fully fleshed out upstream.

doc/integrations/deploy.md

@@ -0,0 +1,49 @@
+# deploy-rs
+[Deploy-rs][d-rs] is a tool for managing NixOS remote machines. It was
+chosen for devos after the author experienced some frustrations with the
+stateful nature of nixops' db. It was also designed from scratch to support
+flake based deployments, and so is an excellent tool for the job.
+
+By default, all the [hosts](../concepts/hosts.md) are also available as deploy-rs nodes,
+configured with the hostname set to `networking.hostName`; overridable via
+the command line.
+
+## Usage
+
+Just add your ssh key to the host:
+```nix
+{ ... }:
+{
+  users.users.${sshUser}.openssh.authorizedKeys.keyFiles = [
+    ../secrets/path/to/key.pub
+  ];
+}
+```
+
+And the private key to your user:
+```nix
+{ ... }:
+{
+  home-manager.users.${sshUser}.programs.ssh = {
+    enable = true;
+
+    matchBlocks = {
+      ${host} = {
+        host = hostName;
+        identityFile = ../secrets/path/to/key;
+        extraOptions = { AddKeysToAgent = "yes"; };
+      };
+    };
+  }
+}
+```
+
+And run the deployment:
+```sh
+deploy "flk#hostName" --hostname host.example.com
+```
+
+> ##### _Note:_
+> Your user will need **passwordless** sudo access
+
+[d-rs]: https://github.com/serokell/deploy-rs

doc/integrations/hercules.md

@@ -0,0 +1,36 @@
+# Hercules CI
+If you start adding your own packages and configurations, you'll probably have
+at least a few binary artifacts. With hercules we can build every package in
+our configuration automatically, on every commit. Additionally, we can have it
+upload all our build artifacts to a binary cache like [cachix][cachix].
+
+This will work whether your copy is a fork, or a bare template, as long as your
+repo is hosted on GitHub.
+
+## Setup
+Just head over to [hercules-ci.com](https://hercules-ci.com) to make an account.
+
+Then follow the docs to set up an [agent][agent], if you want to deploy to a
+binary cache (and of course you do), be sure _not_ to skip the
+[binary-caches.json][cache].
+
+## Ready to Use
+The repo is already set up with the proper _default.nix_ file, building all
+declared packages, checks, profiles and shells. So you can see if something
+breaks, and never build the same package twice!
+
+If you want to get fancy, you could even have hercules
+[deploy your configuration](https://docs.hercules-ci.com/hercules-ci-effects/guide/deploy-a-nixos-machine/)!
+
+> ##### _Note:_
+> Hercules doesn't have access to anything encrypted in the
+> [secrets folder](../../secrets), so none of your secrets will accidentally get
+> pushed to a cache by mistake.
+>
+> You could pull all your secrets via your user, and then exclude it from
+> [allUsers](https://github.com/nrdxp/devos/blob/nrd/suites/default.nix#L17)
+> to keep checks passing.
+
+[agent]: https://docs.hercules-ci.com/hercules-ci/getting-started/#github
+[cache]: https://docs.hercules-ci.com/hercules-ci/getting-started/deploy/nixos/#_3_configure_a_binary_cache
+[cachix]: https://cachix.org

doc/integrations/index.md

@@ -0,0 +1,5 @@
+# Integrations
+This section explores some of the optional tools included with devos to provide
+a solution to common concerns such as ci and remote deployment. An effort is
+made to choose tools that treat nix, and where possible flakes, as first class
+citizens.

doc/integrations/nvfetcher.md

@@ -0,0 +1,43 @@
+# nvfetcher
+[NvFetcher][nvf] is a workflow companion for updating nix sources.
+
+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.
+
+All package source declaration is done in [sources.toml][sources.toml].
+
+From within the devshell of this repo, run `nvfetcher`, a wrapped
+version of `nvfetcher` that knows where to find and place its files
+and commit the results.
+
+## Usage
+
+Statically fetching (not tracking) a particular tag from a github repo:
+```toml
+[manix]
+src.manual = "v0.6.3"
+fetch.github = "mlvzk/manix"
+```
+
+Tracking the latest github _release_ from a github repo:
+```toml
+[manix]
+src.github = "mlvzk/manix" # responsible for tracking
+fetch.github = "mlvzk/manix" # responsible for fetching
+```
+
+Tracking the latest commit of a git repository and fetch from a git repo:
+```toml
+[manix]
+src.git = "https://github.com/mlvzk/manix.git" # responsible for tracking
+fetch.git = "https://github.com/mlvzk/manix.git" # responsible for fetching
+```
+
+> ##### _Note:_
+> Please refer to the [NvFetcher Readme][nvf-readme] for more options.
+
+[nvf]: https://github.com/berberman/nvfetcher
+[nvf-readme]: https://github.com/berberman/nvfetcher#readme
+[sources.toml]: https://github.com/divnix/devos/tree/core/pkgs/sources.toml