diff options
Diffstat (limited to 'builds.sr.ht/installation.md')
| -rw-r--r-- | builds.sr.ht/installation.md | 110 |
1 files changed, 27 insertions, 83 deletions
diff --git a/builds.sr.ht/installation.md b/builds.sr.ht/installation.md index b7201f6..7eb0fe0 100644 --- a/builds.sr.ht/installation.md +++ b/builds.sr.ht/installation.md @@ -4,14 +4,22 @@ 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. -# Prerequisites +# Web service -- [meta.sr.ht](/meta.sr.ht/installation.md) -- [An OAuth client ID and secret for meta.sr.ht](https://meta.sr.ht/oauth) -- PostgreSQL server -- Two redis servers +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. -## Security model +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 @@ -31,91 +39,26 @@ 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). -## PostgreSQL configuration +# Package installation -Start by setting your config.ini's connection string to a superuser, then run -the following commands to create the initial schema: +On each runner, install the builds.sr.ht and builds.sr.ht-images packages. - $ python3 - >>> from buildsrht.app import db - >>> db.create() +# Database configuration -Then 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: +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. +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. -## Redis configuration - -The master server should have two redis servers, one for its own use (as part of -the standard sr.ht configuration) and one for communication with the runners. -Runners should be provided access to only their redis instance - if distributed, -we recommend setting up an SSH tunnel from the master to the runner to offer -access to the appropriate Redis instance. - -## Package installation - -On the master server, install builds.sr.ht either [from -source](https://git.sr.ht/~sircmpwn/builds.sr.ht) or [from -packages](/packages.md). On the runners, install builds.sr.ht and -builds.sr.ht-images, the latter containing templates for our upstream build -images and glue code for running them. - -Place a config file in `/etc/sr.ht/builds.ini` based on -[config.ini.example](https://git.sr.ht/~sircmpwn/builds.sr.ht/tree/config.ini.example). -[Register an OAuth client](https://meta.sr.ht/oauth) and include its client ID -and secret in the config file. Under the `[builds.sr.ht]` section, configure -`redis` on the master to point to the *runner* redis - it will use this to -submit jobs to the runners. The other options are relevant to the build runner, -which we will set up later. - -Start builds.sr.ht (`systemctl start builds.sr.ht` or `service builds.sr.ht -start`) and configure a reverse proxy - here's our nginx configuration for -builds.sr.ht upstream: - - server { - listen 80; - server_name builds.sr.ht; - - location / { - return 302 https://$server_name$request_uri; - } - - location ^~ /.well-known { - root /var/www; - } - } - - server { - listen 443 ssl; - listen [::]:443 ssl; - server_name builds.sr.ht; - client_max_body_size 100M; - ssl_certificate /var/lib/acme/live/builds.sr.ht/fullchain; - ssl_certificate_key /var/lib/acme/live/builds.sr.ht/privkey; - ssl_trusted_certificate /var/lib/acme/live/builds.sr.ht/fullchain; - - location / { - proxy_pass http://127.0.0.1:5002; - } - - location /static { - root /usr/lib/python3.6/site-packages/buildsrht; - } - - location ^~ /.well-known { - root /var/www; - } - } - -## Runner setup +# 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 @@ -136,9 +79,10 @@ build of qemu and nothing else. Next, build any of the images you need: ... and so on ... Note: some images may not build on your host system without the installation of -extra tools, which may not be availalbe. 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. +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 @@ -150,7 +94,7 @@ 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. -## Configuring the runner +# 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 |