There are two components to builds.sr.ht: the job runner and the master server.
Typically installations will have one master and many runners distributed on
many servers, but both can be installed on the same server for small
installations (though [not without risk](#security-model)). We'll start by
setting up the master server.

# Web service

The master server is a standard sr.ht web service and can be [installed as
such](/installation.md). However, it is important that you configure *two* Redis
servers - one that the runners should have access to, and one that they should
not. Insert connection details for the former into build.sr.ht's configuration
file under the `redis` key. Each build runner will also need a local redis
instance running. In an insecure deployment (all services on the same server)
you can get away with a single Redis instance.

We suggest using an SSH tunnel to share the slave Redis instance between job
runners and the master server, but you can use any method you prefer. If you use
an SSH tunnel, you will likely want to use a reverse tunnel initiated from the
master server, so the slaves are unable to SSH into the master server.

# Security model

Let's start with a brief overview of the security model of builds.sr.ht.
Because builds.sr.ht runs arbitrary user code (and allows users to utilize
root), it's important to carefully secure the build environments. To this end,
builds run in a sandbox which consists of:

- A KVM virtual machine via qemu
- Inside of an otherwise empty docker image
- Running as an unprivledged user
- On a server which is isolated by:
    - Being on physically separate server from anything important
    - Using its own isolated redis instance
    - Having minimal database access

We suggest you take similar precautions if your servers could be running
untrusted builds. Remember that if you build only your own software, integration
with other services could end up running untrusted builds (for example,
automatic testing of patches via lists.sr.ht).

# Package installation

On each runner, install the builds.sr.ht and builds.sr.ht-images packages.

# Database configuration

Create two users, one for the master and one for the runners (or one for each
runner if you prefer). They need the following permissions:

- **master** should have ownership over the database and full read/write/alter
  access to all table
- **runner** should have read/write access to the jobs table

If you are running the master and runners on the same server, you will only be
able to use one user - the master user. Configure both the web service and build
runner with this account. Otherwise, two separate accounts is recommended.

Note: in the future runners will not have database access.

# Install images

On the runner, install the `builds.sr.ht-images` package (if building from
source, this package is simply the `images` directory copied to
`/var/lib/images`), as well as docker. Build the docker image like so:

    $ cd /var/lib/images
    $ docker build -t qemu -f qemu/Dockerfile .

This will build a docker image named `qemu` which contains a statically linked
build of qemu and nothing else. Next, build any of the images you need:

    $ cd archlinux
    $ sudo ./genimg
    $ ../control archlinux sanity-check
    $ cd ../debian/jessie
    $ sudo ./genimg
    $ ../../control debian/jessie sanity-check
    ... and so on ...

Note: some images may not build on your host system without the installation of
extra tools, which may or may not be available for your host system. However,
all images can be built on themselves, and a build.yml file is typically
provided which can do the job if run in a similar environment as the target
image.

## Creating new images

If you require any additional images, you should write a `genimg` script which
produces `root.img.qcow2`, `initrd`, and `kernel` files. You should also write a
`functions` script, which is sourced by the control script for booting your
image, installing packages, and so on. Review existing images for guidance, it
should be possible to make virtually any kind of image (including non-Linux
operating systems - the only hard requirement is an ssh daemon) with enough
effort.

# Additional configuration

Write an `/etc/sr.ht/builds.ini` configuration file similar to the one you wrote
on the master server. Only the `[sr.ht]` and `[builds.sr.ht]` sections are
required for the runners. `images` should be set to the installation path of
your images (`/var/lib/images`) and `buildlogs` should be set to the path where
the runner should write its build logs (the runner user should be able to create
files and directories here). Set `runner` to the hostname of the build runner.
You will need to configure nginx to serve the build logs directory in order for
build logs to appear correctly on the website.

Once all of this is done, start the `builds.sr.ht-runner` service and it's off
to the races. Submit builds on the master server and they should run correctly
at this point.