From ad49a5e7e74356cd38c8b8439cbb5d632793c954 Mon Sep 17 00:00:00 2001
From: Timothy DeHerrera <tim.deh@pm.me>
Date: Mon, 15 Feb 2021 11:08:17 -0700
Subject: [PATCH] doc: usage for deploy-rs

---
 SUMMARY.md                 |  2 ++
 doc/integrations/deploy.md | 49 ++++++++++++++++++++++++++++++++++++++
 doc/integrations/index.md  |  5 ++++
 3 files changed, 56 insertions(+)
 create mode 100644 doc/integrations/deploy.md
 create mode 100644 doc/integrations/index.md

diff --git a/SUMMARY.md b/SUMMARY.md
index 410e7973..d921aec2 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -23,4 +23,6 @@
   - [iso](./doc/flk/iso.md)
   - [install](./doc/flk/install.md)
   - [home](./doc/flk/home.md)
+- [Integrations](doc/integrations/index.md)
+  - [deploy-rs](./doc/integrations/deploy.md)
 - [Contributing](./doc/README.md)
diff --git a/doc/integrations/deploy.md b/doc/integrations/deploy.md
new file mode 100644
index 00000000..821afc04
--- /dev/null
+++ b/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 nixflk 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](../../hosts) are also available as deploy-rs nodes,
+configured with the hostname set to `networking.hostName`; overridable via
+the command line.
+
+## Usage
+
+Just add your ssh key to the host:
+```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 sudo access
+
+[d-rs]: https://github.com/serokell/deploy-rs
diff --git a/doc/integrations/index.md b/doc/integrations/index.md
new file mode 100644
index 00000000..f15300c8
--- /dev/null
+++ b/doc/integrations/index.md
@@ -0,0 +1,5 @@
+# Integrations
+This section explores some of the optional tools included with nixflk 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.