Installation of web services uses a mostly consistent procedure across the network. Specific details to each service are available on each service's installation page:

All sysadmins are encouraged to subscribe to the mailing list, a low-volume list of sysadmin-oriented announcements regarding breaking changes, security vulnerabilities, and so on.

General installation instructions follow.

Packages provides a number of Linux distribution package repositories for your use. For details specific to your distribution, see Even if you wish to install services from source, your distribution may not include some of our dependencies and using our package repositories is recommended.

Installation from packages will also give you distro-specific daemon services and will handle database migrations automatically during system updates.


Please send patches to This is also the right place to ask questions about the code. Also check out hacking on for an amended installation procedure for local hacking.


You will need at least:

  • A PostgreSQL server
  • A Redis server
  • A mail server
  • A cron daemon

In order to use most services. core core is a Python package that provides shared functionality across all services. It also contains the default templates and stylesheets that give a consistent look and feel.

The core package is listed as a dependency of the official * packages, so installing it explicitly is not necessary if you are using our package repositories. If you are not using our packages, obtain the source code, initialize submodules and install it like a typical Python package (./ install --prefix=/usr). You will need to install its dependencies beforehand, for an up-to-date list see the package.

Package Installation

Packages are named as you would expect: is called On package managers where dots are not permitted in package names, dashes are used. Underscores are used on systems where dashes are not permitted.

If installing from source, see the packages for an up-to-date list of dependencies and install it like any other Python package: ./ install --prefix=/usr. When installing from source, daemon service files are not provided; you must write one appropriate to your system.

Site Configuration

The config file for all sites is located at /etc/ Each site provides an example configuration in config.example.ini, which includes the global (shared) config options, and any options specific to its operation. You should merge the configs of each site you want to run.

Database Configuration

Start by setting your config.ini's connection string to a superuser, then run the following commands to create the initial schema:

$ python3
>>> from [module].app import db
>>> db.create()

Substitute [module] for the specific application's module, such as metasrht or buildsrht. When complete, you may update your connection string to use a less privileged user.

Schema Upgrades

We use alembic to manage schema migrations. A sample alembic.ini is provided (alembic.ini.example from source and /etc/ from packages), which you should modify to suit your needs - you will probably only need to set the connection string.

Run alembic stamp head once to tell alembic the schema is up-to-date. Future upgrades will be managed automatically by the package, or if you're using the source code you can run alembic upgrade head when you pull the latest version down.

Becoming admin

After setting up and registering yourself a user account, you can give that account admin permissions:

$ python3
>>> from import db, User, UserType
>>> u = User.query.filter_by(username='[your username]').one()
>>> u.user_type = UserType.admin
>>> User.query.session.commit()

Compile static assets

This step is only necessary for users configuring from source. Run make in the root of the repository to compile static assets. will usually do this for you.

Start the service

A service file is included in the packages and uses the same name as the package. On Arch Linux, for example, you can run systemctl enable --now to start up, or rc-update add && service start on Alpine. The service will be running at the port specified in its config file, and you must now prepare to proxy to it.

Proxy configuration

The exact nginx configuration you use will vary depending on your needs. Here is an example for

server {
    listen 80;

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

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

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    client_max_body_size 100M;
    ssl_certificate /var/lib/acme/live/;
    ssl_certificate_key /var/lib/acme/live/;
    ssl_trusted_certificate /var/lib/acme/live/;

    location / {

    location /static {
        root /usr/lib/python3.6/site-packages/metasrht;

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

Once the proxy is configured, you should be able to log into your new service.

Hacking on

If you just want to get the codebase running to hack on it, follow these steps:

  1. Prerequisites
  2. core, however, you can simply clone it somewhere and add it to your Python path. Also export SRHT_PATH=/path/to/ to use your development repository for generating static assets.
  3. Site configuration, but you can just put config.ini in the working directory and will read it there.
  4. Database configuration
  5. Compile static assets
  6. ./ will start the development server.

Table of Contents

This commit

commit 118d9ed010807a82b1f4a1f772040971132568cc
Author: Euan Torano <>
Date:   2018-12-05T01:41:06

Spelling and structural changes for Git documentation.

Fixed some minor spelling mistakes in the index of the Git documentation, and fixed what appears to be an incorrect heading level.
Clone this wiki