First iteration of deployment instructions

4 files changed, 210 insertions, 28 deletions

diff --git a/INSTALL b/INSTALL
index bc04d2e..5239d5d 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,11 +1,186 @@
-Debian/Ubuntu:
-  libapr1-dev /usr/include/apr-1.0
-  apache2-dev /usr/include/apache2
+This guide shows how to install and configure brep on a "deployment" machine as
+opposed to a "development" one (see INSTALL-DEV for latter). Here we assume you
+are using a systemd-based installation. If not, then you will need to replace
+systemctl commands with the equivalend init.d ones.
 
-Fedora/RHEL:
-  apr-devel   /usr/include/apr-1
-  httpd-devel /usr/include/httpd
+1. Create 'brep' User
 
-FreeBSD:
-  apr         /usr/local/include/apr-1
-  apache24    /usr/local/include/apache24
+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 can 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
+assumed to be executed as the brep user and in its home directory.
+
+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.
+
+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) 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 build
+$ cd build
+
+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 http://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;
+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 brep
+$ sudo sudo -u www-data psql -d brep
+
+To troubleshoot, see PostgreSQL logs.
+
+
+5. Create Database Schema and Load Repositories
+
+$ mkdir config
+$ edit config/loader.conf # Capture loader configuration, see brep-loader(1).
+
+$ psql --quiet -f brep/package.sql
+$ install/bin/brep-loader tests/loader/r.conf
+
+To verify:
+
+$ psql -c 'SELECT name, summary FROM repository'
+
+
+6. Setup Apache2 Module
+
+$ cp install/share/brep/etc/brep.conf config/module.conf
+$ edit config/module.conf # Adjust default values if required.
+
+Here we assume you have setup an appropriate Apache2 virtual server. Open the
+corresponding Apache2 .conf file and add the following inside VirtualServer:
+
+        # Load the brep module.
+        #
+        LoadModule brep_module /home/brep/install/libexec/brep/mod_brep.so
+        SetHandler brep
+
+        # 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 Alias directives below.
+        #
+        brep-root /pkg/
+
+        # 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/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>
+
+Restart Apache2:
+
+$ sudo systemctl restart apache2
+
+To verify, visit the repository root. To troubleshoot, see Apache logs.
+
+
+7. Setup Periodic Loader Execution
+
+@@ TODO
+
+
+8. Upgrade procedure
+
+@@ TODO
+
+   - stop apache
+   - suspend periodic loader
+   - migrate schema
+   - resume loader, force a run
+   - start apache
diff --git a/INSTALL-DEV b/INSTALL-DEV
index bac7739..9a2c3d8 100644
--- a/INSTALL-DEV
+++ b/INSTALL-DEV
@@ -13,7 +13,12 @@ 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 --no-mask -Rm 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 that strictly speaking www-data in the above two commands is the Apache2
 group, not user. However, most installations use the same name for both.]
@@ -21,25 +26,24 @@ group, not user. However, most installations use the same name for both.]
 
 1. Create PostgreSQL User and Database
 
-$ sudo su postgres
-$ psql
+$ sudo sudo -u postgres psql # Note: double sudo is not a mistake.
 
 CREATE DATABASE brep;
 CREATE USER <user>;
 GRANT ALL PRIVILEGES ON DATABASE brep TO <user>;
 CREATE USER "www-data" INHERIT IN ROLE <user>;
 
-Exit psql (^D) and postgres login (^D), then make sure the logins work:
+Exit psql (^D), then make sure the logins work:
 
 $ psql -d brep
 $ sudo sudo -u www-data psql -d brep
 
-To troubleshooting, see PostgreSQL logs, for example:
+To troubleshoot, see PostgreSQL logs, for example:
 
 $ sudo tail -f /var/log/postgresql/*.log
 
 
-2. Create Database Schema and Load the Data
+2. Create Database Schema and Load the Repository
 
 All the commands are executed from brep project root.
 
@@ -59,14 +63,21 @@ corresponding Apache2 .conf file and add the following inside VirtualServer,
 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).
 
-        # brep module configuration.
+        # Load the brep module.
         #
         LoadModule brep_module <BREP-OUT-ROOT>/brep/mod_brep.so
         SetHandler brep
 
+        # Repository root. Use / for web server root. And don't forget to also
+        # update the Alias directives below.
+        #
+        root /pkg/
+
+        # Brep module configuration.
+        #
         brep-conf <BREP-SRC-ROOT>/etc/brep.conf
 
-        # brep static content (CSS files).
+        # Static brep content (CSS files).
         #
         # Note: trailing slashes are important!
         #
@@ -84,7 +95,7 @@ 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 troubleshoote, see Apache logs,
-for example:
+To verify, visit the repository root. To troubleshoot, see Apache logs, for
+example:
 
 $ sudo tail -f /var/log/apache2/error.log
diff --git a/brep/options.cli b/brep/options.cli
index aaf0092..d78a19f 100644
--- a/brep/options.cli
+++ b/brep/options.cli
@@ -19,8 +19,8 @@ namespace brep
       dir_path root = "/"
       {
         "<path>"
-        "Repository root. That is, this is the part of the URL from the host
-         name and until the start of the repository. For example, root value
+        "Repository root. That is, this is the part of the URL between the
+         host name and the start of the repository. For example, root value
          '\cb{/pkg/}' means the repository URL is http://example.org/pkg/.
          Specify '\cb{/}' to use the web server root (http://example.org/)."
       }
diff --git a/etc/brep.conf b/etc/brep.conf
index 05981be..26767d6 100644
--- a/etc/brep.conf
+++ b/etc/brep.conf
@@ -1,13 +1,9 @@
 # Configuration file for the brep module (note: this is not an apache2 .conf
-# file). See brep(1) for detailed description of each configuration option.
-# Commented out options indicate their default values.
+# file but it can be converted to one by prefixing all the options with brep-).
+# See brep(1) for detailed description of each configuration option. Commented
+# out options indicate their default values.
 #
 
-# Repository root. Use '/' (default) for web server root.
-#
-root /pkg/
-
-
 # Number of results per page.
 #
 # search-results 10