Diffstat (limited to 'INSTALL')
1 files changed, 57 insertions, 54 deletions
@@ -1,7 +1,8 @@
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.
+replace systemctl commands with the equivalent init.d ones.
1. Create 'brep' User
@@ -16,15 +17,19 @@ without a password:
# 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:
+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.
+ Also make sure the pkg-config (or one of its replacements) is installed.
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
@@ -48,53 +53,40 @@ c) Install PostgreSQL and Apache2 development files. Specifically, we need
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
+d) Unless you already have the build2 toolchain installed, download (normally
+ from 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
+ Note that brep loader (discussed below) runs bpkg so it makes sense to have
+ both from the same release.
- [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:
+3. Build and Install brep
- $ cd libXXX-X.Y.Z
- $ ./configure CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib \
- $ make
- $ sudo make install
+Normally the only extra information that you need to provide on this step is
+the location of the Apache2 headers (httpd.h, etc). Below are their locations
+for some distributions:
- Again, you can use brep's login/home directory for this. See the INSTALL
- file for each library for more information.
+You can also use the Apache2 apxs utility to obtain this information as shown
-3. Build and Install brep
-$ mkdir brep install
+$ mkdir brep
$ 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" \
+bpkg create \
+ cc \
+ config.cc.poptions="-I$(apxs -q includedir)" \
+ config.bin.rpath=/home/brep/install/lib \
-$ bpkg add https://pkg.cppget.org/1/alpha
-$ bpkg fetch
-$ bpkg build brep
-$ bpkg install brep
+bpkg add https://pkg.cppget.org/1/alpha
+bpkg build brep ?sys:libapr1 ?sys:libpq
+bpkg install brep
$ cd .. # Back to brep home.
@@ -137,7 +129,7 @@ $ psql -c 'SELECT name, summary FROM repository'
$ 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:
+If you are happy to run with the default values, you can instead do:
$ ln -s ../install/share/brep/etc/brep-module.conf config/
@@ -186,7 +178,7 @@ can also find this fragment in install/share/brep/etc/brep-apache2.conf):
Alias /pkg/@/ /home/brep/install/share/brep/www/
- Require all granted
+ Require all granted
# You can also serve the repository files from the repository root.
@@ -197,7 +189,7 @@ can also find this fragment in install/share/brep/etc/brep-apache2.conf):
#AliasMatch ^/pkg/(\d+)/(.+) /path/to/repo/$1/$2
- # Require all granted
+ # Require all granted
The output content type of the brep module is application/xhtml+xml and if you
@@ -220,15 +212,15 @@ 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/
+# mkdir -p /etc/systemd/system/apache2.service.d/
+# cat >/etc/systemd/system/apache2.service.d/postgresql.conf
-systemctl cat apache2 # Verify override is listed.
-systemctl restart apache2 # Verify the service still works.
+# systemctl daemon-reload
+# systemctl cat apache2 # Verify override is listed.
+# systemctl restart apache2 # Verify the service still works.
7. Optimize CSS
@@ -244,7 +236,7 @@ $ for i in *.scss; do sassc -s compressed $i `basename -s .scss $i`.css; done
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
+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 loader, then you can set it up as a
system-wide service which runs the loader as the brep user/group. Otherwise, a
@@ -257,7 +249,12 @@ The following crontab entry will execute the loader every five minutes:
$ crontab -
*/5 * * * * $HOME/install/bin/brep-load $HOME/config/brep-load.conf
+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).
8.b Setup Periodic Loader Execution with systemd
@@ -313,8 +310,9 @@ $ cp -r install install-`cat install/share/doc/brep/version`
Build new version of brep:
-$ bpkg fetch -d brep
-$ bpkg build -d brep brep
+$ cd brep
+$ bpkg fetch
+$ bpkg build brep
If you are using a systemd-based setup, then stop and disable the loader:
@@ -333,13 +331,14 @@ $ sudo systemctl stop apache2
Install new brep:
$ rm -rf install/*
-$ bpkg install -d brep brep
+$ 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
-Update database schema:
+Migrate database schema:
@@ -354,10 +353,14 @@ $ systemctl --user enable --now brep-load.timer
If using cron, then simply wait for the next run.
+You can also do a manual load:
+$ install/bin/brep-load config/brep-load.conf
+Next, 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.
+You will also need to repeat the CSS optimization step above.