From c93b55384dd3f04ad816fd9c8484e50ccdc24237 Mon Sep 17 00:00:00 2001
From: Drew DeVault <sir@cmpwn.com>
Date: Thu, 19 Dec 2019 11:05:48 -0500
Subject: [PATCH] Improve config.example.ini

---
 config.example.ini | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/config.example.ini b/config.example.ini
index 5211a1e..52b8c07 100644
--- a/config.example.ini
+++ b/config.example.ini
@@ -16,17 +16,21 @@ owner-email=sir@cmpwn.com
 # The source code for your fork of sr.ht
 source-url=https://git.sr.ht/~sircmpwn/srht
 #
-# A secret key to encrypt session cookies with. Use `srht-keygen service` to
-# generate this. This should be unique to each site, but shared among nodes of
-# that site. For example, git.sr.ht and hg.sr.ht have different keys, but
-# git1.sr.ht has the same key as git2.sr.ht.
+# A key used for encrypting session cookies. Use `srht-keygen service` to
+# generate the service key. This must be shared between each node of the same
+# service (e.g. git1.sr.ht and git2.sr.ht), but different services may use
+# different keys. If you configure all of your services with the same
+# config.ini, you may use the same service-key for all of them.
 service-key=
 #
 # A secret key to encrypt internal messages with. Use `srht-keygen network` to
-# generate this. This should be consistent between all *.sr.ht sites and nodes.
+# generate this key. It must be consistent between all services and nodes.
 network-key=
 #
-# The redis host url.
+# The redis host URL. This is used for caching and temporary storage, and must
+# be shared between nodes (e.g. git1.sr.ht and git2.sr.ht), but need not be
+# shared between services. It may be shared between services, however, with no
+# ill effect, if this better suits your infrastructure.
 redis-host=
 
 [mail]
@@ -42,10 +46,12 @@ smtp-from=
 error-to=
 error-from=
 #
-# Your PGP key information (DO NOT mix up pub and priv here)
-# You must remove the password from your secret key, if present.
-# You can do this with gpg --edit-key [key-id], then use the passwd
-# command and do not enter a new password.
+# You should generate a PGP key to allow users to authenticate emails received
+# from your services. Use `gpg --edit-key [key id]` to remove the password from
+# your private key, then export it to a file and set pgp-privkey to the path to
+# that file. pgp-pubkey should be set to the path to your public key, and
+# pgp-key-id should be set to the key ID string. Outgoing emails are signed with
+# this PGP key.
 pgp-privkey=
 pgp-pubkey=
 pgp-key-id=
@@ -53,10 +59,11 @@ pgp-key-id=
 [webhooks]
 #
 # base64-encoded Ed25519 key for signing webhook payloads. This should be
-# consistent for all *.sr.ht sites, as we'll use this key to verify signatures
-# from other sites in your network.
+# consistent between all services.
 #
-# Use the srht-webhook-keygen command to generate a key.
+# Use the `srht-keygen webhook` command to generate this key. Put the private
+# key here and distribute the public key to anyone who would want to verify
+# webhook payloads from your service.
 private-key=
 
 [man.sr.ht]