diff options
| -rw-r--r-- | sr.ht/configuration_reference.md | 245 |
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. |