From b15d964d899c844eb2b4d92b8242480f8a557d5b Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Thu, 17 Dec 2015 14:09:35 +0200 Subject: First iteration of deployment instructions --- INSTALL | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- INSTALL-DEV | 31 ++++++--- brep/options.cli | 4 +- etc/brep.conf | 10 +-- 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 and 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 -I" \ + 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). + # + + Error "mod_alias is not enabled" + + + # Note: trailing slashes are important! + # + Alias /pkg/@/ /home/brep/install/share/brep/www/ + + + Require all granted + + + # 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 + # + # + # Require all granted + # + +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 ; GRANT ALL PRIVILEGES ON DATABASE brep TO ; CREATE USER "www-data" INHERIT IN ROLE ; -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 and 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/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 /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 = "/" { "" - "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 -- cgit v1.1