From 64e566a49c672c289a2680c477843f4eaeb77d96 Mon Sep 17 00:00:00 2001
From: aszlig <aszlig@redmoonstudios.org>
Date: Thu, 7 Apr 2016 14:11:49 +0200
Subject: [PATCH] nixos/taskserver: Add module documentation

It's not by any means exhaustive, but we're still going to change the
implementation, so let's just use this as a starting point.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
---
 .../manual/configuration/configuration.xml    |  1 +
 nixos/doc/manual/default.nix                  |  1 +
 .../services/misc/taskserver/default.nix      |  8 ++-
 .../modules/services/misc/taskserver/doc.xml  | 52 +++++++++++++++++++
 4 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 nixos/modules/services/misc/taskserver/doc.xml

diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index caba8fb1f4ad..501ad10788c5 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -28,6 +28,7 @@ effect after you run <command>nixos-rebuild</command>.</para>
 <xi:include href="postgresql.xml" />
 <xi:include href="gitlab.xml" />
 <xi:include href="acme.xml" />
+<xi:include href="taskserver.xml" />
 
 <!-- Apache; libvirtd virtualisation -->
 
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 746ddc071b6a..130b016aa266 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -58,6 +58,7 @@ let
       cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml
       cp ${../../modules/services/misc/gitlab.xml} configuration/gitlab.xml
       cp ${../../modules/security/acme.xml} configuration/acme.xml
+      cp ${../../modules/services/misc/taskserver/doc.xml} configuration/taskserver.xml
       ln -s ${optionsDocBook} options-db.xml
       echo "${version}" > version
     '';
diff --git a/nixos/modules/services/misc/taskserver/default.nix b/nixos/modules/services/misc/taskserver/default.nix
index 1279e548c2a1..3a9669ddd266 100644
--- a/nixos/modules/services/misc/taskserver/default.nix
+++ b/nixos/modules/services/misc/taskserver/default.nix
@@ -88,6 +88,8 @@ let
 
   ctlcmd = "${nixos-taskserver}/bin/nixos-taskserver --service-helper";
 
+  withMeta = meta: defs: mkMerge [ defs { inherit meta; } ];
+
 in {
 
   options = {
@@ -299,7 +301,9 @@ in {
     };
   };
 
-  config = mkIf cfg.enable {
+  config = withMeta {
+    doc = ./taskserver.xml;
+  } (mkIf cfg.enable {
 
     environment.systemPackages = [ pkgs.taskserver nixos-taskserver ];
 
@@ -424,5 +428,5 @@ in {
         Group = cfg.group;
       };
     };
-  };
+  });
 }
diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml
new file mode 100644
index 000000000000..b41747872c66
--- /dev/null
+++ b/nixos/modules/services/misc/taskserver/doc.xml
@@ -0,0 +1,52 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    version="5.0"
+    xml:id="module-taskserver">
+
+  <title>Taskserver</title>
+
+  <para>
+    Taskserver is the server component of
+    <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
+    open source todo list application.
+  </para>
+
+  <para>
+    <emphasis>Upstream documentation:</emphasis>
+    <link xlink:href="https://taskwarrior.org/docs/#taskd"/>
+  </para>
+
+  <section>
+    <title>Configuration</title>
+
+    <para>
+      Taskserver does all of its authentication via TLS using client
+      certificates, so you either need to roll your own CA or purchase a
+      certificate from a known CA, which allows creation of client
+      certificates.
+
+      These certificates are usually advertised as
+      <quote>server certificates</quote>.
+    </para>
+
+    <para>
+      So in order to make it easier to handle your own CA, there is a helper
+      tool called <command>nixos-taskserver</command> which manages the custom
+      CA along with Taskserver users and groups.
+    </para>
+
+    <para>
+      While the client certificates in Taskserver only authenticate whether a
+      user is allowed to connect, every user has its own UUID which identifies
+      it as an entity.
+    </para>
+
+    <para>
+      With <command>nixos-taskserver</command> the client certificate is created
+      along with the UUID of the user, so it handles all of the credentials
+      needed in order to setup the Taskwarrior client to work with a Taskserver.
+    </para>
+
+    <!-- TODO: Go more into the details of nixos-taskserver. -->
+  </section>
+</chapter>