From dd0d64afea9f184e4408016ed1413e2284cc67a2 Mon Sep 17 00:00:00 2001
From: aszlig <aszlig@redmoonstudios.org>
Date: Tue, 12 Apr 2016 06:19:59 +0200
Subject: nixos/taskserver: Finish module documentation

Apart from the options manual, this should cover the basics for setting
up a Taskserver. I am not a native speaker so this can and (probably)
should be improved, especially the wording/grammar.

Signed-off-by: aszlig <aszlig@redmoonstudios.org>
---
 nixos/modules/services/misc/taskserver/doc.xml | 96 +++++++++++++++++++++++++-
 1 file changed, 94 insertions(+), 2 deletions(-)

(limited to 'nixos/modules')

diff --git a/nixos/modules/services/misc/taskserver/doc.xml b/nixos/modules/services/misc/taskserver/doc.xml
index b41747872c66..15125b1411bd 100644
--- a/nixos/modules/services/misc/taskserver/doc.xml
+++ b/nixos/modules/services/misc/taskserver/doc.xml
@@ -32,7 +32,7 @@
     <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.
+      CA along with Taskserver organisations, users and groups.
     </para>
 
     <para>
@@ -46,7 +46,99 @@
       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>
+  </section>
+
+  <section>
+    <title>The nixos-taskserver tool</title>
+
+    <para>
+      Because Taskserver by default only provides scripts to setup users
+      imperatively, the <command>nixos-taskserver</command> tool is used for
+      addition and deletion of organisations along with users and groups defined
+      by <option>services.taskserver.organisations</option> and as well for
+      imperative set up.
+    </para>
+
+    <para>
+      The tool is designed to not interfere if the command is used to manually
+      set up some organisations, users or groups.
+    </para>
+
+    <para>
+      For example if you add a new organisation using
+      <command>nixos-taskserver org add foo</command>, the organisation is not
+      modified and deleted no matter what you define in
+      <option>services.taskserver.organisations</option>, even if you're adding
+      the same organisation in that option.
+    </para>
+
+    <para>
+      The tool is modelled to imitate the official <command>taskd</command>
+      command, documentation for each subcommand can be shown by using the
+      <option>--help</option> switch.
+    </para>
+  </section>
+  <section>
+    <title>Declarative/automatic CA management</title>
+
+    <para>
+      Everything is done according to what you specify in the module options,
+      however in order to set up a Taskwarrior client for synchronisation with a
+      Taskserver instance, you have to transfer the keys and certificates to the
+      client machine.
+    </para>
 
-    <!-- TODO: Go more into the details of nixos-taskserver. -->
+    <para>
+      This is done using
+      <command>nixos-taskserver user export $orgname $username</command> which
+      is printing a shell script fragment to stdout which can either be used
+      verbatim or adjusted to import the user on the client machine.
+    </para>
+
+    <para>
+      For example, let's say you have the following configuration:
+<screen>
+{
+  services.taskserver.enable = true;
+  services.taskserver.fqdn = "server";
+  services.taskserver.listenHost = "::";
+  services.taskserver.organisations.NixOS.users = [ "alice" ];
+}
+</screen>
+      This creates an organisation called <literal>NixOS</literal> with the user
+      <literal>alice</literal>.
+    </para>
+
+    <para>
+      Now in order to import the <literal>alice</literal> user to another
+      machine <literal>alicebox</literal>, all we need to do is something like
+      this:
+<screen>
+$ ssh server nixos-taskserver user export NixOS alice | sh
+</screen>
+      Of course, if no SSH daemon is available on the server you can also copy
+      &amp; paste it directly into a shell.
+    </para>
+
+    <para>
+      After this step the user should be set up and you can start synchronising
+      your tasks for the first time with <command>task sync init</command> on
+      <literal>alicebox</literal>.
+    </para>
+
+    <para>
+      Subsequent synchronisation requests merely require the command
+      <command>task sync</command> after that stage.
+    </para>
+  </section>
+  <section>
+    <title>Manual CA management</title>
+
+    <para>
+      If you set any options within
+      <option>service.taskserver.pki.manual.*</option>, the automatic user and
+      CA management by the <command>nixos-taskserver</command> is disabled and
+      you need to create certificates and keys by yourself.
+    </para>
   </section>
 </chapter>
-- 
cgit 1.4.1