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 equivalend init.d ones.

1. Create 'brep' User

This user will be used to run the brep repository loader. We will also use its
home directory to build and install the brep module, store its configuration,
etc. 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. 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.x and Apache2 using your distribution's packages.

   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 and web server development files.
   Below are the names of their packages for some distributions:

   Debian/Ubuntu: libpq-dev            libapr1-dev  apache2-dev
   Fedora/RHEL:   posqtgresql-devel    apr-devel    httpd-devel
   FreeBSD:       postgresql94-client  apr          apache24

d) Download (normally from the same place where you obtained brep, e.g.,
   https://download.build2.org) and install build2-toolchain by following its
   INSTALL file instructions. You can build build2-toolchain using brep's
   login and in its home directory.

e) Install libodb-pgsql and libstudxml

   [Currently we use pre-release versions of these libraries so they have to
   be built from source.]

   Download source packages for the two libraries from the same location as
   build2-toolchain. Then unpack, build, and install:

   $ cd libXXX-X.Y.Z
   $ ./configure CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib \
     --prefix=/usr/local
   $ make
   $ sudo make install

   Again, you can use brep's login/home directory for this. See the INSTALL
   file for each library for more information.


3. Build and Install brep

$ mkdir brep install
$ cd brep

In the following command line, replace <apr> and <apache> with directories
that contain the apr.h and httpd.h headers, respectively. Below are their
locations for some distributions:

Debian/Ubuntu: /usr/include/apr-1.0      /usr/include/apache2
Fedora/RHEL:   /usr/include/apr-1        /usr/include/httpd
FreeBSD:       /usr/local/include/apr-1  /usr/local/include/apache24

$ bpkg create                                                   \
  cxx                                                           \
  config.cxx.poptions="-I/usr/local/include -I<apr> -I<apache>" \
  config.cxx.loptions=-L/usr/local/lib                          \
  config.bin.rpath="/home/brep/install/lib /usr/local/lib"      \
  config.install.root=/home/brep/install

$ bpkg add https://pkg.cppget.org/1/alpha
$ bpkg fetch
$ bpkg build brep
$ bpkg install brep

$ cd .. # Back to brep home.


4. Create PostgreSQL User and Database

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

CREATE DATABASE brep TEMPLATE template0 ENCODING 'UTF8'
LC_COLLATE 'en_US.UTF8' LC_CTYPE 'en_US.UTF8';
CREATE USER brep;
GRANT ALL PRIVILEGES ON DATABASE brep TO brep;
CREATE USER "www-data" INHERIT IN ROLE brep;

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

$ psql
^D
$ sudo sudo -u www-data psql -d brep
^D

To troubleshoot, see PostgreSQL logs.


5. Create Database Schema and Load Repositories

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

$ install/bin/brep-migrate
$ install/bin/brep-load config/brep-load.conf

To verify:

$ psql -c 'SELECT name, summary FROM repository'


6. Setup Apache2 Module

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

If you happy to run with the default values, you can instead do:

$ ln -s ../install/share/brep/etc/brep-module.conf config/

Here we assume you have setup an appropriate Apache2 virtual server. Open the
corresponding Apache2 .conf file and add the following inside VirtualHost (you
can also find this fragment in install/share/brep/etc/brep-apache2.conf):

        # Load the brep module.
        #
        LoadModule brep_module /home/brep/install/libexec/brep/mod_brep.so

        # Repository root. This is the part of the URL between the host name
        # and the start of the repository. For example, root value /pkg means
	# the repository URL is http://example.org/pkg/. Specify / to use the
        # web server root (e.g., http://example.org/). If using a different
        # repository root, don't forget to also change Location and Alias
	# directives below.
        #
        brep-root /pkg

        <Location "/pkg">
          SetHandler brep

          <IfModule dir_module>
            DirectoryIndex disabled
            DirectorySlash Off
          </IfModule>
        </Location>

        # Brep module configuration. If you prefer, you can paste the contents
        # of this file here. However, you will need to prefix every option with
        # 'brep-'.
        #
        brep-conf /home/brep/config/brep-module.conf

        # Static brep content (CSS files).
        #
        <IfModule !alias_module>
          Error "mod_alias is not enabled"
        </IfModule>

        # Note: trailing slashes are important!
        #
        Alias /pkg/@/ /home/brep/install/share/brep/www/

        <Directory "/home/brep/install/share/brep/www">
            Require all granted
        </Directory>

        # You can also serve the repository files from the repository root.
        # For example:
        #
        #   http://example.org/pkg/1/...  -> /path/to/repo/1/...
        #
        #AliasMatch ^/pkg/(\d+)/(.+) /path/to/repo/$1/$2
        #
        #<Directory "/path/to/repo">
        #    Require all granted
        #</Directory>

The output content type of the brep module is application/xhtml+xml and if you
would like to make sure it gets 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/css

Restart Apache2:

$ sudo systemctl restart apache2

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


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 Execution

Initially this guide suggested using systemd user session support to run the
loader. However, the current state of user sessions has one major drawback:
they are not strated/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 loader, then you can set it up as a
system-wide service which runs the loader as the brep user/group. Otherwise, a
cron job is a natural choice.


8.a Setup Periodic Loader Execution with cron

The following crontab entry will execute the loader every five minutes:

$ crontab -
MAILTO=<brep-admin-email>
*/5 * * * * $HOME/install/bin/brep-load $HOME/config/brep-load.conf


8.b Setup Periodic Loader Execution with systemd

In this version we will use the systemd user session to periodically run the
loader 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 loader 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/

Start the service to make sure there are no issues:

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

Start the timer and monitor it to make sure it fires:

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

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

$ systemctl --user enable brep-load.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:

$ bpkg -d brep build brep

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

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

If you are using a cron-based setup, then it is not worth it commenting out the
job entry. If the new version of the loader 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 -d brep install brep

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

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

Update database schema:

$ install/bin/brep-migrate

If using systemd, then start and enable the loader:

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

If everything looks good, enable periodic execution:

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

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

Start apache:

$ sudo systemctl start apache2

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

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