~sircmpwn/sr.ht-docs

20a59da64e2177e4516596f20100fbb69d82e520 — Drew DeVault 2 months ago 7f24bc7 
Add API configuration to installation docs
patch browse 
4 files changed, 58 insertions(+), 248 deletions(-)

M configuration.md
M git.sr.ht/installation.md
M meta.sr.ht/installation.md
D sr.ht/configuration_reference.md

M configuration.md => configuration.md +56 -3
@@ 63,9 63,62 @@ your unified `config.ini`.
## Service Files

Service files for daemons are pre-configured by their distribution packages.

Thus, after setting up your `config.ini` appropriately, you may start them
using your distribution's service manager (e.g., `service git.sr.ht start`).
After setting up your `config.ini` appropriately, you may start them using your
distribution's service manager (e.g., `service git.sr.ht start`).

The list of daemons available for each service are documented on their
respective installation page.

# Web services

Most sr.ht services include a web component, and the standard installation
procedure requires you to configure a reverse proxy to serve them. A typical
nginx configuration may look something like this:

```
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:5000;
    }

    location /query {
        proxy_pass http://127.0.0.1:5100;
    }

    location /static {
        root /usr/lib/python3.8/site-packages/metasrht;
    }
}
```

Note the following requirements:

- Proxy `/` to the web application
- Serve static assets from `/static` (optional, but recommended)
- For many services, `/query` should be proxied to the API service

See [sr.ht-nginx](https://git.sr.ht/~sircmpwn/sr.ht-nginx) for the nginx
configurations we use in production.

# Databases



M git.sr.ht/installation.md => git.sr.ht/installation.md +1 -0
@@ 13,6 13,7 @@ installation](/installation.md#installing-from-packages).
## Daemons

- `git.sr.ht` - The web service.
- `git.sr.ht-api` - The API service.
- `git.sr.ht-webhooks` - Webhook delivery service.

## Cronjobs


M meta.sr.ht/installation.md => meta.sr.ht/installation.md +1 -0
@@ 18,6 18,7 @@ installation process](/installation.md#installing-from-packages).
## Daemons

- `meta.sr.ht` - The web service.
- `meta.sr.ht-api` - The API service.
- `meta.sr.ht-webhooks` - Webhook delivery service.

## Cronjobs


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