From aaad9fd0daadffa53a65cdeff3a060f0c59db417 Mon Sep 17 00:00:00 2001
From: Mike Sperber <sperber@deinprogramm.de>
Date: Sat, 2 May 2020 16:18:29 +0200
Subject: nixos/doc: Rudimentary documentation for Subversion-inside-Apache
 HTTP.

Content thanks to: Aaron Andersen
---
 nixos/doc/manual/configuration/configuration.xml |   1 +
 nixos/doc/manual/configuration/subversion.xml    | 140 +++++++++++++++++++++++
 2 files changed, 141 insertions(+)
 create mode 100644 nixos/doc/manual/configuration/subversion.xml

diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml
index 6eb8f50baca..2d7d22e3bb5 100644
--- a/nixos/doc/manual/configuration/configuration.xml
+++ b/nixos/doc/manual/configuration/configuration.xml
@@ -22,6 +22,7 @@
  <xi:include href="xfce.xml" />
  <xi:include href="networking.xml" />
  <xi:include href="linux-kernel.xml" />
+ <xi:include href="subversion.xml" />
  <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
  <xi:include href="profiles.xml" />
  <xi:include href="kubernetes.xml" />
diff --git a/nixos/doc/manual/configuration/subversion.xml b/nixos/doc/manual/configuration/subversion.xml
new file mode 100644
index 00000000000..940d63cc4e6
--- /dev/null
+++ b/nixos/doc/manual/configuration/subversion.xml
@@ -0,0 +1,140 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="module-services-subversion">
+  <title>Subversion</title>
+
+ <para>
+  <link xlink:href="https://subversion.apache.org/">Subversion</link>
+  is a centralized version-control system.  It can use a <link
+  xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.choosing">variety
+  of protocols</link> for communication between client and server.
+ </para>
+ <section xml:id="module-services-subversion-apache-httpd">
+  <title>Subversion inside Apache HTTP</title>
+
+   <para>
+   This section focuses on configuring a web-based server on top of
+   the Apache HTTP server, which uses
+   <link xlink:href="http://www.webdav.org/">WebDAV</link>/<link
+   xlink:href="http://www.webdav.org/deltav/WWW10/deltav-intro.htm">DeltaV</link>
+   for communication.
+   </para>
+
+   <para>For more information on the general setup, please refer to
+   the <link
+   xlink:href="http://svnbook.red-bean.com/en/1.7/svn-book.html#svn.serverconfig.httpd">the
+   appropriate section of the Subversion book</link>.
+   </para>
+
+   <para>To configure, include in
+   <literal>/etc/nixos/configuration.nix</literal> code to activate
+   Apache HTTP, setting <xref linkend="opt-services.httpd.adminAddr" />
+   appropriately:
+   </para>
+
+    <para>
+<programlisting>
+  services.httpd.enable = true;
+  services.httpd.adminAddr = ...;
+  networking.firewall.allowedTCPPorts = [ 80 443 ];
+</programlisting>
+    </para>
+
+    <para>For a simple Subversion server with basic authentication,
+    configure the Subversion module for Apache as follows, setting
+    <literal>hostName</literal> and <literal>documentRoot</literal>
+    appropriately, and <literal>SVNParentPath</literal> to the parent
+    directory of the repositories,
+    <literal>AuthzSVNAccessFile</literal> to the location of the
+    <code>.authz</code> file describing access permission, and
+    <literal>AuthUserFile</literal> to the password file.
+    </para>
+    <para>
+<programlisting>
+services.httpd.extraModules = [
+    # note that order is *super* important here
+    { name = "dav_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_dav_svn.so"; }
+    { name = "authz_svn"; path = "${pkgs.apacheHttpdPackages.subversion}/modules/mod_authz_svn.so"; }
+  ];
+  services.httpd.virtualHosts = {
+    "svn" = {
+       hostName = HOSTNAME;
+       documentRoot = DOCUMENTROOT;
+       locations."/svn".extraConfig = ''
+           DAV svn
+           SVNParentPath REPO_PARENT
+           AuthzSVNAccessFile ACCESS_FILE
+           AuthName "SVN Repositories"
+           AuthType Basic
+           AuthUserFile PASSWORD_FILE
+           Require valid-user
+      '';
+    }
+</programlisting>
+    </para>
+
+    <para>
+    The key <code>"svn"</code> is just a symbolic name identifying the
+    virtual host.  The <code>"/svn"</code> in
+    <code>locations."/svn".extraConfig</code> is the path underneath
+    which the repositories will be served.
+    </para>
+
+    <para><link
+              xlink:href="https://wiki.archlinux.org/index.php/Subversion">This
+    page</link> explains how to set up the Subversion configuration
+    itself.  This boils down to the following:
+    </para>
+    <para>
+      Underneath <literal>REPO_PARENT</literal> repositories can be set up
+      as follows:
+    </para>
+    <para>
+<screen>
+<prompt>$ </prompt> svn create REPO_NAME
+</screen>
+    </para>
+    <para>Repository files need to be accessible by
+    <literal>wwwrun</literal>:
+    </para>
+    <para>
+<screen>
+<prompt>$ </prompt> chown -R wwwrun:wwwrun REPO_PARENT
+</screen>
+    </para>
+    <para>
+      The password file <literal>PASSWORD_FILE</literal> can be created as follows:
+    </para>
+    <para>
+<screen>
+<prompt>$ </prompt> htpasswd -cs PASSWORD_FILE USER_NAME
+</screen>
+    </para>
+    <para>
+    Additional users can be set up similarly, omitting the
+    <code>c</code> flag:
+    </para>
+    <para>
+<screen>
+<prompt>$ </prompt> htpasswd -s PASSWORD_FILE USER_NAME
+</screen>
+    </para>
+    <para>
+      The file describing access permissions
+      <literal>ACCESS_FILE</literal> will look something like
+      the following:
+    </para>
+    <para>
+<programlisting>
+[/]
+* = r
+
+[REPO_NAME:/]
+USER_NAME = rw
+</programlisting>
+    </para>
+    <para>The Subversion repositories will be accessible as <code>http://HOSTNAME/svn/REPO_NAME</code>.</para>
+ </section>
+</chapter>
-- 
cgit 1.4.1