This guide shows how to install and configure brep on a "deployment" machine as
opposed to a "development" one (see INSTALL-DEV for the latter). Here we assume
you are using a systemd-based distribution. If not, then you will need to
replace systemctl commands with the equivalent init.d ones.

The below instructions include steps for setting up brep as the build2 build
bot controller, package submission, and CI request services. All these
functionalities are optional and, if not needed, then the corresponding steps
can be omitted.

1. Create 'brep' User

This user will be used to run the brep package database loader, build database
cleaner, monitor, and database schemas migration utility. We will also use its
home directory to build and install the brep module, store its configuration,
etc.

Note: if the deployment machine employs SELinux, then this approach may
require additional configuration steps (not shown) in order to allow Apache2
access to the module, configuration, and content (or, alternatively, a
different deployment approach).

We create this user with a disabled password so only root will be able to
operate as brep. Because of this restriction we will allow brep to run sudo
without a password:

# adduser --disabled-password brep
# echo "brep ALL=(ALL) NOPASSWD:ALL" >/etc/sudoers.d/brep
# chmod 0440 /etc/sudoers.d/brep

In the rest of this guide commands that start with the $ shell prompt are
expected to be executed as the brep user and in its home directory (those
that start with # as above are run as root). To change to the brep user
from root, do:

# su -l brep


2. Install Prerequisites

a) Install a C++ compiler using your distribution's package.

b) Install PostgreSQL 9.3 or above (including the contrib package containing
   the postgres_fdw extension) as well as Apache2 using your distribution's
   packages. Below are the names of these packages for some distributions:

   Debian/Ubuntu: postgresql           postgresql-contrib    apache2
   Fedora/RHEL:   postgresql-server    postgresql-contrib    httpd
   FreeBSD:       postgresqlXY-server  postgresqlXY-contrib  apache24

   Also check that the files in /home/brep are readable by "others". If they
   are not, then run the following command to grant Apache2 read access:

   $ setfacl -m g:www-data:rx /home/brep
   $ setfacl -dm g:www-data:rx /home/brep

   In the above command and in the rest of this guide replace www-data with
   the user name under which Apache2 is running (See the "User" directive in
   the Apache2 .conf file).

   [Note that strictly speaking www-data in the above command is the Apache2
   group, not user. However, most installations use the same name for both.]

c) Install PostgreSQL and Apache2 development files. Specifically, we need
   PostgreSQL's libpq and Apache's libapr, libapreq, and web server development
   files. Below are the names of their packages for some distributions:

   Debian/Ubuntu: libpq-dev           libapr1-dev libapreq2-dev   apache2-dev
   Fedora/RHEL:   postgresql-devel    apr-devel   libapreq2-devel httpd-devel
   FreeBSD:       postgresqlXY-client apr         libapreq2       apache24

d) Unless you already have the build2 toolchain, install it by following
   instructions on https://build2.org/install.xhtml.

   Note that brep loader (discussed below) runs bpkg so it makes sense to have
   both from the same release.

3. Build and Install brep

$ mkdir brep
$ cd brep

$ bpkg create                         \
   cc                                 \
   config.cc.coptions=-O3             \
   config.bin.rpath=$HOME/install/lib \
   config.install.root=$HOME/install

$ bpkg add https://pkg.cppget.org/1/alpha
$ bpkg fetch
$ bpkg build brep ?sys:libapr1 ?sys:libapreq2 ?sys:libpq
$ bpkg install brep

$ cd .. # Back to brep home.

Note that by default the location of the Apache2 headers (httpd.h, etc) is
detected automatically, using the Apache2 apxs utility. Below are their
locations for some distributions:

Debian/Ubuntu: /usr/include/apache2
Fedora/RHEL:   /usr/include/httpd
FreeBSD:       /usr/local/include/apache24

To disable this functionality and specify the location explicitly, you can
configure brep in the development mode and specify the respective preprocessor
option by, for example, adding the following configuration variables to the
above bpkg-build command:

config.brep.develop=true
config.cc.poptions="-I..."


4. Create PostgreSQL User and Databases

Note that the brep_package and brep_build databases can reside in different
database instances, potentially on different hosts. If this is the case then
the following commands must be adjusted accordingly.

Note also that below unless you set a custom password for the brep-build
database user, any locally logged-in user will be able to login as brep-build
and gain full access to the brep_package database.

$ sudo sudo -u postgres psql # Note: double sudo is not a mistake.

CREATE DATABASE brep_package
  TEMPLATE template0
  ENCODING 'UTF8'
  LC_COLLATE 'en_US.UTF8'
  LC_CTYPE 'en_US.UTF8';

CREATE DATABASE brep_build
  TEMPLATE template0
  ENCODING 'UTF8'
  LC_COLLATE 'en_US.UTF8'
  LC_CTYPE 'en_US.UTF8';

CREATE USER brep;

GRANT ALL PRIVILEGES ON DATABASE brep_package, brep_build TO brep;

CREATE USER "www-data" INHERIT IN ROLE brep;

CREATE USER "brep-build" INHERIT IN ROLE brep PASSWORD '-';

Exit psql (^D), then make sure the logins work:

$ psql -d brep_package
^D
$ psql -d brep_build
^D
$ sudo sudo -u www-data psql -d brep_package
^D
$ sudo sudo -u www-data psql -d brep_build
^D

To troubleshoot, see PostgreSQL logs.

Next setup the connection between databases:

$ sudo sudo -u postgres psql -d brep_build

CREATE EXTENSION postgres_fdw;

CREATE SERVER package_server
  FOREIGN DATA WRAPPER postgres_fdw
  OPTIONS (dbname 'brep_package', updatable 'true');

GRANT USAGE ON FOREIGN SERVER package_server to brep;

CREATE USER MAPPING FOR PUBLIC
  SERVER package_server
  OPTIONS (user 'brep-build', password '-');

Note that starting with PostgreSQL 15 only the database owner can create the
objects in the public schema by default. Thus, if the PostgreSQL version is 15
or above, then all the privileges on this schema in the created databases need
to be granted explicitly by the postgres user to the brep user:

\c brep_package
GRANT ALL PRIVILEGES ON SCHEMA public TO brep;

\c brep_build
GRANT ALL PRIVILEGES ON SCHEMA public TO brep;

Exit psql (^D)

The user brep-build is required (by the postgres_fdw extension) to login with
password. To accomplish this, add the following line to the PostgreSQL client
authentication configuration file (pg_hba.conf):

# TYPE  DATABASE      USER        ADDRESS  METHOD
local   brep_package  brep-build           md5

Restart PostgreSQL:

$ sudo systemctl restart postgresql

Enable creating database tables with columns of the case-insensitive character
string type:

$ sudo sudo -u postgres psql -d brep_package

CREATE EXTENSION citext;

Exit psql (^D)

$ sudo sudo -u postgres psql -d brep_build

CREATE EXTENSION citext;

Exit psql (^D)


5. Create Database Schemas and Load Repositories

$ mkdir config
$ edit config/loadtab # Loader configuration, see brep-load(1).

$ install/bin/brep-migrate package
$ install/bin/brep-load config/loadtab

$ install/bin/brep-migrate build

To verify:

$ psql -d brep_package -c 'SELECT canonical_name, summary FROM repository'
$ psql -d brep_build -c 'SELECT package_name FROM build' # Empty row set.
$ psql -d brep_build -c 'SELECT DISTINCT name FROM build_package'


6. Setup Apache2 Module

$ cp install/share/brep/etc/brep-module.conf config/
$ edit config/brep-module.conf # Adjust default values if required.

To enable the build2 build bot controller functionality you will need to set
the build-config option in brep-module.conf. To also enable the build
artifacts upload functionality you will need to specify the upload-data
directory for the desired upload types in brep-module.conf. For example, for
generated binary distribution packages it can be as follows:

upload-data bindist=/home/brep/bindist-data

Note that this directory must exist and have read, write, and execute
permissions granted to the www-data user. This, for example, can be achieved
with the following commands:

$ mkdir /home/brep/bindist-data
$ setfacl -m g:www-data:rwx /home/brep/bindist-data

For sample upload handler implementations see brep/handler/upload/.

To enable the package submission functionality you will need to specify the
submit-data and submit-temp directories in brep-module.conf. Note that these
directories must exist and have read, write, and execute permissions granted
to the www-data user. This, for example, can be achieved with the following
commands:

$ mkdir /home/brep/submit-data
$ mkdir /home/brep/submit-temp
$ setfacl -m g:www-data:rwx /home/brep/submit-data
$ setfacl -m g:www-data:rwx /home/brep/submit-temp

To also enable the package submission web form set the submit-form option. You
can use the installed sample submission form fragment or create a custom one
if your submission handler requires additional information (besides the
package archive and its SHA256 checksum) to be supplied by the client. For
example:

$ cp install/share/brep/www/submit.xhtml config/
$ edit config/submit.xhtml # Add custom form fields, adjust CSS style, etc.

For sample submission handler implementations see brep/handler/submit/.

To enable the CI request functionality you will need to specify the ci-data
directory in brep-module.conf. Note that this directory must exist and have
read, write, and execute permissions granted to the www-data user. This, for
example, can be achieved with the following commands:

$ mkdir /home/brep/ci-data
$ setfacl -m g:www-data:rwx /home/brep/ci-data

To also enable the CI request submission web form set the ci-form option. You
can use the installed sample CI form fragment or create a custom one if your
CI request handler requires additional information (besides the repository URL
and optional package name[/version]) to be supplied by the client. For
example:

$ cp install/share/brep/www/ci.xhtml config/
$ edit config/ci.xhtml # Add custom form fields, adjust CSS style, etc.

For sample CI request handler implementations see brep/handler/ci/.

Here we assume you have setup an appropriate Apache2 virtual server. Open the
corresponding Apache2 .conf file and add the contents of
brep/etc/brep-apache2.conf into the <VirtualHost> section.

The output content types of the brep module are application/xhtml+xml,
text/manifest and text/plain. If you would like to make sure they get
compressed (along with linked CSS), also add the following lines:

        # Compress brep output (xhtml+xml) and CSS.
        #
        AddOutputFilterByType DEFLATE application/xhtml+xml
        AddOutputFilterByType DEFLATE text/manifest
        AddOutputFilterByType DEFLATE text/plain
        AddOutputFilterByType DEFLATE text/css

Restart Apache2:

$ sudo systemctl restart apache2

To verify, visit the repository root. To troubleshoot, see Apache logs.

Now that Apache2 loads the brep module which requires PostgreSQL, it is a good
idea to make the Apache2 service depend on PostgreSQL so that they are started
in proper order. Here is how we can do it with systemd (with newer versions
you can use 'systemctl edit' instead of mkdir and cat):

# mkdir -p /etc/systemd/system/apache2.service.d/
# cat >/etc/systemd/system/apache2.service.d/postgresql.conf
[Unit]
Requires=postgresql.service
After=postgresql.service
^D

# mkdir -p /etc/systemd/system/postgresql.service.d/
# cat >/etc/systemd/system/postgresql.service.d/apache2.conf
[Unit]
Wants=apache2.service
^D

# systemctl daemon-reload
# systemctl cat apache2       # Verify override is listed.
# systemctl cat postgresql    # Verify override is listed.
# systemctl stop postgresql
# systemctl status apache2    # Verify stopped.
# systemctl start postgresql
# systemctl status apache2    # Verify started.


7. Optimize CSS

This step is optional and involves optimizing the CSS files used by brep. For
example, using the sassc(1) command line tool:

$ cd install/share/brep/www/
$ for i in *.scss; do sassc -s compressed $i `basename -s .scss $i`.css; done


8. Setup Periodic Loader, Cleaner, and Monitor Execution

Initially this guide suggested using systemd user session support to run the
loader, cleaner, and monitor. However, the current state of user sessions has
one major drawback: they are not started/attached-to when logging in with su
-l (see Debian bug #813789 for details). This limitation makes them unusable
in our setup. If you still would like to use systemd to run the utilities,
then you can set it up as a system-wide service which runs them as the brep
user/group. Otherwise, a cron job is a natural choice.

Note that the builds cleaner execution is optional and is only required if the
build2 build bot functionality is enabled (see the build bot documentation for
details). If it is disabled in you setup, then skip the cleaner-related parts
in the subsequent subsections.

If the build artifacts upload functionality is enabled in addition to the
build2 build bot functionality you most likely will want to additionally setup
the cleanup of the outdated build artifacts. For example, for binary
distribution package uploads handled by brep-upload-bindist the cleanup needs
to be performed by periodic execution of brep-upload-bindist-clean script.
Note that the directory where the uploads are saved to must exist and have
read, write, and execute permissions granted to the brep user. This, for
example, can be achieved with the following commands:

# mkdir /var/bindist
# chown www-data:www-data /var/bindist
# setfacl -m u:brep:rwx /var/bindist
# setfacl -dm u:brep:rwx /var/bindist

If the CI request functionality is enabled you most likely will want to
additionally setup the tenants cleanup.

The monitor execution is also optional and currently only makes sense if the
build2 build bot functionality is enabled. Note that you may need to replace
the public toolchain name argument in the monitor utility command with a real
list of toolchain names (and optionally versions) used in the brep build
infrastructure.


8.a Setup Periodic Loader, Cleaner, and Monitor Execution with cron

The following crontab entries will execute the loader every five minutes, the
tenants, builds, and binary distribution cleaners once a day at midnight, and
the monitor every hour (all shifted by a few minutes in order not to clash
with other jobs):

$ crontab -l
MAILTO=<brep-admin-email>
PATH=/usr/local/bin:/bin:/usr/bin
*/5 * * * * $HOME/install/bin/brep-load $HOME/config/loadtab
1 0 * * * $HOME/install/bin/brep-clean tenants 240
2 0 * * * $HOME/install/bin/brep-clean builds $HOME/config/buildtab
3 0 * * * $HOME/install/bin/brep-upload-bindist-clean /var/bindist 2880
4 * * * * $HOME/install/bin/brep-monitor --report-timeout 86400 --clean $HOME/config/brep-module.conf public
^D

Note that here we assume that bpkg (which is executed by brep-load) is in one
of the PATH's directories (usually /usr/local/bin).

To additionally load the package metadata (reviews, etc) to the database, the
brep-load-with-metadata wrapper script can be used instead of brep-load
directly. In this case, the package git repository that contains the owners/
metadata directory should be pre-cloned (read-only and shallowly) as follows:

$ git init public-metdata
$ cd public-metdata
$ git remote add origin <repository-url>
$ git config core.sparsecheckout true
$ echo "owners/" > .git/info/sparse-checkout
$ git pull --depth=1 origin master

And the above crontab brep-load entry needs to be replaced with the following
version:

$HOME/install/bin/brep-load-with-metadata --timeout 60 /home/brep/public-metdata $HOME/config/loadtab


8.b Setup Periodic Loader, Cleaner, and Monitor Execution with systemd

In this version we will use the systemd user session to periodically run the
loader, cleaner, and monitor as the brep user. If your installation doesn't
use systemd, then a cron job would be a natural alternative (see above).

As the first step, make sure systemd user sessions support is working for the
brep user:

$ systemctl --user status

If there are any errors, make sure the dbus and libpam-systemd packages are
installed, relogin as brep, and try again. If it still doesn't work, google
for the error message and your distribution name.

Next enable the brep's systemd session to remain running after logging off
since we want the utilities to run even when we are not logged in:

$ sudo loginctl enable-linger brep

$ mkdir -p .config/systemd/user
$ cp install/share/brep/etc/systemd/brep-load.* .config/systemd/user/
$ cp install/share/brep/etc/systemd/brep-clean.* .config/systemd/user/
$ cp install/share/brep/etc/systemd/brep-monitor.* .config/systemd/user/

Start the service to make sure there are no issues:

$ systemctl --user start brep-load.service
$ journalctl

$ systemctl --user start brep-clean.service
$ journalctl

$ systemctl --user start brep-monitor.service
$ journalctl

Start the timers and monitor them to make sure they fire:

$ systemctl --user start brep-load.timer
$ systemctl --user start brep-clean.timer
$ systemctl --user start brep-monitor.timer
$ journalctl -f

If everything looks good, enable the timer to be started at boot time:

$ systemctl --user enable brep-load.timer
$ systemctl --user enable brep-clean.timer
$ systemctl --user enable brep-monitor.timer


9. Upgrade Procedure

During upgrade we will stop apache for what should normally be a short period
of time. To ensure that there are no surprises, for production environments it
is generally recommended to first perform the upgrade on a staging machine, for
example, a VM with an identical setup.

Save the previous installation and configuration, for example, using the
brep version as a suffix:

$ cp -r config config-`cat install/share/doc/brep/version`
$ cp -r install install-`cat install/share/doc/brep/version`

Build new version of brep:

$ cd brep
$ bpkg fetch
$ bpkg build brep

If you are using a systemd-based setup, then stop and disable the loader,
cleaner, and monitor:

$ systemctl --user disable --now brep-load.timer
$ systemctl --user disable --now brep-clean.timer
$ systemctl --user disable --now brep-monitor.timer
$ systemctl --user stop brep-load.service
$ systemctl --user stop brep-clean.service
$ systemctl --user stop brep-monitor.service

If you are using a cron-based setup, then it is not worth it commenting out the
job entries. If the new version of the brep utilities gets executed before or
during the migration, then it will fail and you will get an email with the
diagnostics. Other than that, it should be harmless.

Stop apache:

$ sudo systemctl stop apache2

Install new brep:

$ rm -rf ../install/*
$ bpkg install brep
$ cd ..

Review brep-module.conf changes that may need to be merged:

$ diff -u install/share/brep/etc/brep-module.conf config/brep-module.conf

Migrate database schemas:

$ install/bin/brep-migrate package
$ install/bin/brep-migrate build

Note that if instead you need to recreate the whole databases (e.g., migration
is not possible), then one way to do it would be:

$ psql -d brep_package -c 'DROP OWNED BY brep'
$ psql -d brep_build -c 'DROP OWNED BY brep'

If using systemd, then start and enable the loader, cleaner, and monitor:

$ systemctl --user start brep-load.service
$ systemctl --user status brep-load.service
$ systemctl --user start brep-clean.service
$ systemctl --user status brep-clean.service
$ systemctl --user start brep-monitor.service
$ systemctl --user status brep-monitor.service

If everything looks good, enable periodic execution:

$ systemctl --user enable --now brep-load.timer
$ systemctl --user enable --now brep-clean.timer
$ systemctl --user enable --now brep-monitor.timer

If using cron, then simply wait for the next run.

You can also do a manual load:

$ install/bin/brep-load config/loadtab

Next, start apache:

$ sudo systemctl start apache2

To verify, visit the repository root. To troubleshoot, see Apache logs.

You will also need to repeat the CSS optimization step above.