aboutsummaryrefslogtreecommitdiff
path: root/INSTALL
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 /INSTALL
parent08732655b4842807b6a7b8f6086e40a9237c8ee5 (diff)
First iteration of deployment instructions
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL193
1 files changed, 184 insertions, 9 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