Add sr.ht config reference page

1 files changed, 245 insertions, 0 deletions

diff --git a/sr.ht/configuration_reference.md b/sr.ht/configuration_reference.md
new file mode 100644
index 0000000..1d69876
--- /dev/null
+++ b/sr.ht/configuration_reference.md
@@ -0,0 +1,245 @@
+---
+title: Configuration Reference
+---
+
+This document covers the configuration options common to all sr.ht
+services.
+
+# sr.ht
+
+Configuration options that apply to all sr.ht services.
+
+## site-name
+
+The name of your network of sr.ht-based sites.
+
+```ini
+[sr.ht]
+site-name=sourcehut
+```
+
+## site-info
+
+Top-level information page for your site.
+
+```ini
+[sr.ht]
+site-info=sourcehut
+```
+
+## site-blurb
+
+A catchy one-liner describing your site.
+
+```ini
+[sr.ht]
+site-blurb=the hacker's forge
+```
+
+## environment
+
+The environment name, e.g. `production` or `development`. `production` is
+recommended for live user-facing installations.
+
+```ini
+[sr.ht]
+environment=development
+```
+
+## owner-name
+
+Name of site owner.
+
+```ini
+[sr.ht]
+owner-name=Drew DeVault
+```
+
+## owner-email
+
+Email of site owner.
+
+```ini
+[sr.ht]
+owner-email=sir@cmpwn.com
+```
+
+## source-url
+
+The source code for your fork of sr.ht.
+
+```ini
+[sr.ht]
+source-url=https://git.sr.ht/~sircmpwn/srht
+```
+
+**NOTICE**: SourceHut uses the AGPL license, which requires you to publish any
+modifications you make to the source code under the same AGPL license.
+
+## service-key
+
+A secret key used to encrypt internal messages. To generate the key, run
+`srht-keygen service`.
+
+```ini
+[sr.ht]
+service-key=SERVICE_KEY
+```
+
+<div class="alert alert-warning">
+  <strong>Warning:</strong> If you configure load balancing for a sr.ht
+  service, the service keys must be consistent across all nodes of the
+  service.
+</div>
+
+<div class="alert alert-info">
+  <strong>Note:</strong> For asymmetric keys (i.e., a public/private key pair),
+  store the private key in your <code>config.ini</code> and distribute the
+  public key to any relevant parties.
+</div>
+
+## network-key
+
+A secret key used to encrypt and sign internal service-to-service
+communications. To generate the key, run `srht-keygen network`.
+
+```ini
+[sr.ht]
+network-key=NETWORK_KEY
+```
+
+<div class="alert alert-warning">
+  <strong>Warning:</strong> The key must be consistent across all services
+  and nodes within your deployment.
+</div>
+
+## redis-host
+
+The [Redis](https://redis.io) host URL, which is used for caching.
+
+```ini
+[sr.ht]
+redis-host=
+```
+
+# webhooks
+
+## webhook-key
+
+A secret key used to sign webhook payloads for authenticating requests and
+internal webhooks. To generate the key, run `srht-keygen webhook`.
+
+```ini
+[webhooks]
+webhook-key=WEBHOOK_KEY
+```
+
+<div class="alert alert-warning">
+  <strong>Warning:</strong> The key must be consistent across all services
+  and nodes within your deployment.
+</div>
+
+# mail
+
+Configuration options for outgoing emails.
+
+## smtp-host
+
+```ini
+[mail]
+smtp-host=
+```
+
+## smtp-port
+
+```ini
+[mail]
+smtp-port=
+```
+
+## smtp-user
+
+```ini
+[mail]
+smtp-user=
+```
+
+## smtp-password
+
+```ini
+[mail]
+smtp-password=
+```
+
+## smtp-from
+
+```ini
+[mail]
+smtp-from=
+```
+
+## error-to
+
+Email address to which diagnostic application exceptions are sent.
+
+```ini
+[mail]
+error-to=
+```
+
+## error-from
+
+Email address from which diagnostic application exceptions are sent.
+
+```ini
+[mail]
+error-from=
+```
+
+## pgp-privkey
+
+## pgp-pubkey
+
+## pgp-key-id
+
+<div class="alert alert-warning">
+  <strong>Warning:</strong> In order for sr.ht services to sign (and optionally
+  encrypt) outgoing emails, you must generate a PGP key without a password.
+</div>
+
+# Proxy
+
+Here is an example Nginx configuration for meta.sr.ht:
+
+    server {
+        listen 80;
+        server_name meta.sr.ht;
+
+        location / {
+            return 302 https://$server_name$request_uri;
+        }
+
+        location ^~ /.well-known {
+            root /var/www;
+        }
+    }
+
+    server {
+        listen 443 ssl http2;
+        listen [::]:443 ssl http2;
+        server_name meta.sr.ht;
+        client_max_body_size 100M;
+        ssl_certificate /etc/ssl/uacme/meta.sr.ht/cert.pem;
+        ssl_certificate_key /etc/ssl/uacme/private/meta.sr.ht/key.pem;
+
+        location / {
+            proxy_pass http://127.0.0.1:5002;
+        }
+
+        location /static {
+            root /usr/lib/python3.6/site-packages/metasrht;
+        }
+    }
+
+See [sr.ht-nginx](https://git.sr.ht/~sircmpwn/sr.ht-nginx) for the nginx
+configurations we use in production.