This document provides general information about the configuration process of services.

Similar to the installation process, configuring services typically involves steps that are specific each service. That being said, they all share certain aspects which are described below. Be sure to take a look at each service's configuration page for more details:


Before configuring any service, ensure that you have the following services installed. Every service makes use of them, so your deployment will likely not work as expected if they are missing.

  • — Provides functionality used by all services.

    • For users installing from packages, this package is automatically pulled in as a dependency.

    • For users installing from source, this package must be built first.

      Note: The dependencies in may not be up-to-date. For an up-to-date list of dependencies, consult the latest Alpine package.
  • — Performs various administrative tasks (e.g., storing account details, handling logins, SSH and PGP key storage).


config.ini services all use a shared configuration file, located at /etc/ The specific options you will configure will depend on the subset of and configuration of services you choose to run.

Each service provides an example configuration file, called config.example.ini, in their source code repository, with annotations explaining each configuration option. You should consult these when creating your unified config.ini.

Service Files

Service files for daemons are pre-configured by their distribution packages. After setting up your config.ini appropriately, you may start them using your distribution's service manager (e.g., service start).

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

Web services

Most 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;

    location / {
        return 302 https://$server_name$request_uri;

    location ^~ /.well-known {
        root /var/www;

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    client_max_body_size 100M;
    ssl_certificate /etc/ssl/uacme/;
    ssl_certificate_key /etc/ssl/uacme/private/;

    location / {

    location /query {

    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 for the nginx configurations we use in production.


Each service requires its own database. It is recommended to give each service its own database login, with full permissions for its database so that it may manage its own schema migrations.

Once you populate the connection-string field in your config.ini, you may use the schema.sql file to populate the database (e.g. psql -d -f schema.sql to set up's database).

Note that if you have not configured SSL for your PostgreSQL server, you may have to append ?sslmode=disable to your connection string for some services to work.

Schema Upgrades

We use alembic to manage schema migrations. We use custom scripts to automatically retrieve database credentials from your config.ini. If you have installed from distribution packages, set [<service>] migrate-on-upgrade=yes to have migrations automatically performed during normal service upgrades (e.g., [] migrate-on-upgrade=yes).

Otherwise, you may use srht-migrate <service> upgrade head to run updates for migrations, and <service>-migrate upgrade head to run service-specific upgrades. For example, to upgrade the database schema for, run srht-migrate upgrade head, then gitsrht-migrate upgrade head. Other alembic commands are available, use gitsrht-migrate --help for more information.

Upgrade Procedure

  1. Stop all services.
  2. Update and upgrade your packages (e.g. apk update && apk upgrade).
  3. Resume all services.

If you have high availability requirements, the web services may be load-balanced to avoid an outage.

Database migrations will be performed automatically during upgrades. We source your alembic config from your main config.ini, so there's no need to write an alembic.ini file.

Run srht-migrate <service> stamp head && <service>-migrate stamp head once to tell alembic the schema is up-to-date (e.g. srht-migrate stamp head && mansrht-migrate stamp head). Future upgrades will be managed automatically by the package, or if you're using the source code you can run srht-migrate <service> upgrade head && <service>-migrate upgrade head when you pull the latest version down.


Many services are able to integrate with third-party tools, such as:

About this wiki

commit 267a92d91115d0b1925b8dca3528bb3ceb95977e
Author: Simon Ser <>
Date:   2024-04-18T20:49:49+00:00 drop FreeBSD maintainership
Clone this wiki (read-only) (read/write)