The goal of this setup is to run the brep Apache2 modules from the development
build while still being as close to the real deployment as possible. To this
end, we use default, system-wide installations of both Apache2 and Postgres.

In the below instructions replace <user> with your login and www-data with the
user under which Apache2 is running (See the "User" directive in the Apache2
.conf file).


0. Check Permissions

Check that the files in the brep/ directory are readable by "others". If they
are not, then run the following two commands to grant Apache2 read access:

$ setfacl -Rdm g:www-data:rx brep
$ setfacl -n -Rm g:www-data:rx brep

And also for all the directories leading up to brep/, for example, if you have
~/projects/brep/, then:

$ setfacl -m g:www-data:rx ~/ ~/projects

Note: strictly speaking www-data in the above two commands is the Apache2
group, not user. However, most installations use the same name for both.

Note: if the development 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. Alternatively, you may
want to disable the security restrictions for Apache2, for example:

semanage permissive -a httpd_t


1. Create PostgreSQL User and Databases

$ 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 <user>;

GRANT ALL PRIVILEGES ON DATABASE brep_package, brep_build TO <user>;

CREATE USER "www-data" INHERIT IN ROLE <user>;

CREATE USER "brep-build" INHERIT IN ROLE <user> 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 <user>:

\c brep_package
GRANT ALL PRIVILEGES ON SCHEMA public TO <user>;

\c brep_build
GRANT ALL PRIVILEGES ON SCHEMA public TO <user>;

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

$ 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 <user>;

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

Exit psql (^D)

Add the following lines at the beginning of the PostgreSQL client
authentication configuration file (pg_hba.conf):

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

Restart PostgreSQL (use the second version for systemd):

$ sudo /etc/init.d/postgresql restart
$ sudo systemctl restart postgresql

To troubleshoot, see PostgreSQL logs, for example:

$ sudo tail -f /var/log/postgresql/*.log

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)


2. Create Database Schemas and Load the Repository

All the commands are executed from brep project root.

$ migrate/brep-migrate package

# Or use some other loader config.
#
$ load/brep-load --bpkg ../bpkg/bpkg/bpkg tests/load/loadtab

$ migrate/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'


3. Setup Apache2 Module

Here we assume Apache2 is installed and you have an appropriate VirtualHost
ready (the one for the default site is usually a good candidate). Open the
corresponding Apache2 .conf file and add the following inside VirtualHost,
replacing <BREP-OUT-ROOT> and <BREP-SRC-ROOT> with the actual absolute paths
(if you built brep in the source tree, then the two would be the same), and
replacing <user> with your login.

        # Load the brep module.
        #
        <IfModule !brep_module>
          LoadModule brep_module <BREP-OUT-ROOT>/mod/mod_brep.so
        </IfModule>

        # Repository email. This email is used for the From: header in emails
        # send by brep (for example, build failure notifications).
        #
        brep-email admin@example.org

        # Repository host. It specifies the scheme and the host address (but
        # not the root path; see brep-root below) that will be used whenever
        # brep needs to construct an absolute URL to one of its locations (for
        # example, a link to a build log that is being send via email).
        #
        brep-host https://example.org

        # Repository root. Use / for web server root. And don't forget to also
        # update the Location and Alias directives below.
        #
        brep-root /pkg

        <Location "/pkg">
          SetHandler brep

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

        # Brep module configuration.
        #
        brep-conf <BREP-SRC-ROOT>/etc/brep-module.conf
        brep-package-db-role <user>
        brep-build-db-role <user>

        # Static brep content (CSS files).
        #
        # Note: trailing slashes are important!
        #
        Alias /pkg/@/ <BREP-SRC-ROOT>/www/

        <Directory "<BREP-SRC-ROOT>/www">
            Require all granted
        </Directory>

You may want to replace <BREP-SRC-ROOT>/etc/brep-module.conf with a custom
configuration file if you often need to modify it.

Restart Apache2 (use the second version for systemd):

$ sudo /etc/init.d/apache2 restart
$ sudo systemctl restart apache2

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

$ sudo tail -f /var/log/apache2/error.log


4. Reloading During Development

To do a "complete reload" (i.e., recreate database schemas, load the repository
data, and reload the Apache2 plugin), execute the following from brep/:

$ migrate/brep-migrate --recreate package
$ migrate/brep-migrate --recreate build
$ load/brep-load --bpkg ../bpkg/bpkg/bpkg tests/load/loadtab
$ sudo /etc/init.d/apache2 restart
$ sudo systemctl restart apache2

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 <user>'
$ psql -d brep_build -c 'DROP OWNED BY <user>'