Update git.sr.ht installation/config pages

3 files changed, 120 insertions, 91 deletions

diff --git a/git.sr.ht/configuration.md b/git.sr.ht/configuration.md
new file mode 100644
index 0000000..092ab8d
--- /dev/null
+++ b/git.sr.ht/configuration.md
@@ -0,0 +1,107 @@
+---
+title: git.sr.ht Configuration
+---
+
+This document covers the configuration process for git.sr.ht.
+
+# Cronjobs
+
+- `gitsrht-periodic`: The recommended configuration is
+  `*/20 * * * * gitsrht-periodic`.
+
+# Storage
+
+## Repository
+
+<div class="alert alert-info">
+  <strong>Note:</strong> If git.sr.ht was installed in a package, you may skip
+  this section.
+</div>
+
+As a repository hosting service, git.sr.ht requires a place for storing
+repositories (we recommend `/var/lib/git/`). It also requires a `git` user who
+has ownership over the repository storage location.
+
+## Objects
+
+To allow users to upload artifacts to git repositories, an S3-compatible object
+storage system may be set up and configured (separately from the repository
+storage) before filling out the S3-related configuration options in your
+`config.ini`.
+
+<div class="alert alert-danger">
+  <strong>Warning:</strong> You must secure the S3 storage to protect from
+  unauthorized downloads of artifacts within private repositories. git.sr.ht
+  will stream artifact downloads directly from the S3 storage after confirming
+  authorization, so you simply need to avoid configuring the bucket for public
+  access.
+</div>
+
+<div class="alert alert-info">
+  <strong>Note:</strong> For object storage, we recommend
+  <a href="https://min.io" class="alert-link">MinIO</a>,
+  a free and open-source S3-compatible storage server.
+</div>
+
+# SSH Dispatch
+
+It is necessary to configure git.sr.ht's SSH dispatcher as the system-wide SSH
+authorization hook. First you need to install `go`, then build the dispatcher
+with `go install` in the `gitsrht-dispatch` repository. The `gitsrht-shell`
+helper is also written in Go, run the same process from its directory.
+
+In `/etc/ssh/sshd_config`, configure gitsrht-dispatch like so:
+
+    AuthorizedKeysCommand=/usr/bin/gitsrht-dispatch "%u" "%h" "%t" "%k"
+    AuthorizedKeysCommandUser=root
+    PermitUserEnvironment SRHT_*
+
+`sshd` will invoke our dispatcher whenever a connection is made to the server
+to obtain a list of authorized keys for the connecting user. The default
+behavior is to read the `.ssh/authorized_keys` file from that user's HOME
+directory, but the dispatcher can also "dispatch" to other authentication tools
+for other users. This is used to authorize and perform git operations via the
+`gitsrht-keys` and `gitsrht-shell`. See the `[dispatch]` section of your
+git.sr.ht configuration for details on how this works and how to configure it
+for additional services (e.g. man.sr.ht).
+
+Authorization logs are written to `/var/log/gitsrht-dispatch` and
+`gitsrht-shell`.
+
+# HTTP(S) Cloning
+
+git.sr.ht does not handle HTTP(S) cloning for you, so you'll need to set it up
+yourself with your web server. Here's an example Nginx configuration:
+
+```nginx
+location = /authorize {
+    proxy_pass http://127.0.0.1:5001;
+    proxy_pass_request_body off;
+    proxy_set_header Content-Length "";
+    proxy_set_header X-Original-URI $request_uri;
+}
+
+location ~ ^/([^/]+)/([^/]+)/(HEAD|info/refs|objects/info/.*|git-upload-pack).*$ {
+    auth_request /authorize;
+    root /var/lib/git;
+    fastcgi_pass unix:/run/fcgiwrap.sock;
+    fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
+    fastcgi_param PATH_INFO $uri;
+    fastcgi_param GIT_PROJECT_ROOT $document_root;
+    fastcgi_param GIT_HTTP_EXPORT_ALL "";
+    include fastcgi_params;
+    gzip off;
+}
+```
+
+It is important that you set up the `/authorize` endpoint to enforce the
+privacy of private repositories.
+
+If you don't have `/run/fcgiwrap.sock` on your system, you'll need to install
+the `fcgiwrap` package.
+
+<div class="alert alert-info">
+  <strong>Note:</strong> On some systems, the script might be called
+  `/run/fcgiwrap.socket`, `/run/fcgiwrap/fcgiwrap.sock`, or something else
+  entirely. Consult your distribution's documentation.
+</div>
diff --git a/git.sr.ht/configuration_reference.md b/git.sr.ht/configuration_reference.md
new file mode 100644
index 0000000..a7a4b59
--- /dev/null
+++ b/git.sr.ht/configuration_reference.md
@@ -0,0 +1,5 @@
+---
+title: git.sr.ht Configuration Reference
+---
+
+This document covers the configuration options for the git.sr.ht service.
diff --git a/git.sr.ht/installation.md b/git.sr.ht/installation.md
index c86a309..71018c9 100644
--- a/git.sr.ht/installation.md
+++ b/git.sr.ht/installation.md
@@ -1,103 +1,20 @@
 ---
-title: git.sr.ht installation
+title: git.sr.ht Installation
 ---
 
-git.sr.ht is the git repository hosting service for the sr.ht network.
+This document covers the installation steps for git.sr.ht, a git repository
+hosting service.
 
 # Installation
 
-git.sr.ht is a standard sr.ht web service and can be installed through the
-[standard procedure](/installation.md). However, there are several additional
-steps required.
+git.sr.ht can be installed through [package
+installation](/installation.md#installing-from-packages).
 
 ## Daemons
 
-- `git.sr.ht`: the web service
-- `git.sr.ht-webhooks`: webhook delivery service
+- `git.sr.ht` - The web service.
+- `git.sr.ht-webhooks` - Webhook delivery service.
 
 ## Cronjobs
 
-- `gitsrht-periodic`: various maintenance tasks. Recommended configuration is
-  `*/20 * * * * gitsrht-periodic`
-
-## Repository storage
-
-You will need to set up a directory for repositories to be stored in - we
-suggest `/var/lib/git/`. Also configure a `git` user and assign ownership over
-`/var/lib/git/` to this user. The git.sr.ht package will automatically prepare
-these for you. If you do not use the package, you must create the user yourself
-and ensure that the git.sr.ht web application runs as this user.
-
-## Object storage
-
-To allow users to upload artifacts to git repositories, you need to configure an
-S3-compatible object storage system separately, then fill out the s3-related
-configuration options in config.ini. We recommend MinIO as a free-software
-S3-compatible object storage server.
-
-Please be aware that it is your responsibility to secure the S3 storage to
-protect artifacts of private repositories from unauthorized downloads. git.sr.ht
-will stream artifact downloads directly from S3 after confirming authorization,
-so you simply need to avoid configuring the bucket for public access.
-
-## SSH dispatch
-
-It is necessary to configure git.sr.ht's SSH dispatcher as the system-wide SSH
-authorization hook. First you need to install `go`, then build the dispatcher
-with `go install` in the `gitsrht-dispatch` repository. The `gitsrht-shell`
-helper is also written in Go, run the same process from its directory.
-
-
-In `/etc/ssh/sshd_config`, configure gitsrht-dispatch like so:
-
-```
-AuthorizedKeysCommand=/usr/bin/gitsrht-dispatch "%u" "%h" "%t" "%k"
-AuthorizedKeysCommandUser=root
-PermitUserEnvironment SRHT_*
-```
-
-sshd will invoke our dispatcher whenever a connection is made to the server to
-obtain a list of authorized keys for the connecting user. The default behavior
-is to read the `.ssh/authorized_keys` file from that user's HOME directory, but
-the dispatcher can also "dispatch" to other authentication tools for other
-users. This is used to authorize and perform git operations via the
-`gitsrht-keys` and `gitsrht-shell`. See the `[dispatch]` section of your
-git.sr.ht configuration for details on how this works and how to configure it
-for additional services (e.g. man.sr.ht).
-
-Authorization logs are written to `/var/log/gitsrht-dispatch` and
-`gitsrht-shell`.
-
-## HTTP(s) Cloning
-
-git.sr.ht does not do this for you - you need to wire it up in nginx. Here's an
-example config:
-
-```nginx
-location = /authorize {
-    proxy_pass http://127.0.0.1:5001;
-    proxy_pass_request_body off;
-    proxy_set_header Content-Length "";
-    proxy_set_header X-Original-URI $request_uri;
-}
-
-location ~ ^/([^/]+)/([^/]+)/(HEAD|info/refs|objects/info/.*|git-upload-pack).*$ {
-    auth_request /authorize;
-    root /var/lib/git;
-    fastcgi_pass unix:/run/fcgiwrap.sock;
-    fastcgi_param SCRIPT_FILENAME /usr/lib/git-core/git-http-backend;
-    fastcgi_param PATH_INFO $uri;
-    fastcgi_param GIT_PROJECT_ROOT $document_root;
-    fastcgi_param GIT_HTTP_EXPORT_ALL "";
-    include fastcgi_params;
-    gzip off;
-}
-```
-
-It's important that you set up the `/authorize` endpoint to enforce the privacy
-of private repositories.
-
-If you don't have `/run/fcgiwrap.sock` on your system, you'll need to install
-the `fcgiwrap` package (for instance: `apt-get install fcgiwrap`). On some
-systems, the script might be `/run/fcgiwrap.socket` or
-`/run/fcgiwrap/fcgiwrap.sock`.
+- `gitsrht-periodic` - Performs various maintenance tasks.