aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2015-12-17 14:09:35 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2015-12-17 14:09:35 +0200
commitb15d964d899c844eb2b4d92b8242480f8a557d5b (patch)
treea10de5991f722df2c188b332bf670fe6a2e4f537
parent08732655b4842807b6a7b8f6086e40a9237c8ee5 (diff)
First iteration of deployment instructions
-rw-r--r--INSTALL193
-rw-r--r--INSTALL-DEV31
-rw-r--r--brep/options.cli4
-rw-r--r--etc/brep.conf10
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