~sircmpwn/sr.ht-docs

a00bb5faf6a705088d59989c0419b311bfbcceab — Jason Phan 2 months ago 2320a55
Add sr.ht config reference page
1 files changed, 245 insertions(+), 0 deletions(-)

A sr.ht/configuration_reference.md
A sr.ht/configuration_reference.md => sr.ht/configuration_reference.md +245 -0
@@ 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.