Installation on Linux

This chapter describes how to install the CBGM application on a linux server. If you want to run the application on a desktop machine an installation with Docker might be the easier way to go.

Install Prerequisites

The application should run as a user that has no special privileges.

Warning

Do not run the application as a user with administrative rights.

As a user with admin privileges do:

1. Create user ntg

   sudo useradd -m -d /home/ntg -s /bin/bash -U ntg
   sudo passwd ntg
   

2. Install the software:

   sudo apt-get update
   sudo apt-get install git make
   sudo -u ntg bash
   
   mkdir -p ~/prj/ntg
   cd !!$
   git clone https://github.com/cceh/ntg
   cd ntg
   exit
   
   sudo bash
   cd ~ntg/prj/ntg/ntg/
   make install-prerequisites
   

Database Access

MySQL database

1. Edit (or create) your ~/.my.cnf and add this section:

   [mysql]
   host="localhost"
   user="<username>"
   password="<password>"
   default-character-set="utf8"
   

   Replace <username> and <password> with your own MySQL username and password.

   Warning

   Make sure ~/.my.cnf is readable only by yourself!

2. Create databases for ECM, Leitzeile and VarGenAtt:

   sudo mysql -e "CREATE DATABASE ECM_ActsPh4"
   sudo mysql -e "CREATE DATABASE Nestle29"
   sudo mysql -e "CREATE DATABASE VarGenAtt_ActPh4"
   

Postgres database

0. Make sure you have the following lines in pg_hba.conf so you can connect to postgres using password identification.

   # IPv4 local connections:
   host    all             all             127.0.0.1/32            md5
   # IPv6 local connections:
   host    all             all             ::1/128                 md5
   

1. Create a postgres user and a foreign data wrapper for MySQL. The FDW allows Postgres to access the MySQL databases.

   Login as administrative user and say:

   sudo -u postgres psql
   

   CREATE USER ntg CREATEDB PASSWORD '<password>';
   CREATE DATABASE ntg_user OWNER ntg;
   \q
   

   Replace <password> with a real password.

   sudo -u postgres ~ntg/prj/ntg/ntg/scripts/cceh/create_database.sh acts_ph4
   

   Logout.

2. Edit (or create) your ~/.pgpass and add this line:

   Login as user ntg and say:

   localhost:5432:*:ntg:<password>
   

   Warning

   Make sure ~/.pgpass is readable only by yourself!

   Note

   You can now login to the Postgres database as user ntg without having to enter your password:

   psql acts_ph4
   

   Logout.

Application server

1. Configure the global settings for the application server. This configures the user management database that holds user credentials and the sending of confirmation mails.

   Login as user ntg and edit (or create) your server/instance/_global.conf

   APPLICATION_NAME    = "Root"
   APPLICATION_ROOT    = "/"
   SESSION_COOKIE_PATH = "/"
   SECRET_KEY          = "<a long random string>"
   
   PGHOST="localhost"
   PGPORT="5432"
   PGDATABASE="ntg_user"
   PGUSER="ntg"
   
   USER_PASSWORD_HASH="pbkdf2_sha512"
   USER_PASSWORD_SALT="<a random string>"
   
   MAIL_SERVER  = "smtp.domain.tld"
   MAIL_PORT    = 25
   MAIL_USE_TLS = True
   MAIL_DEFAULT_SENDER = "ntg appserver <noreply@domain.tld>"
   

2. Configure the CBGM database or databases. Create one .conf file per database, the name of the file may be chosen at will but should not start with an underscore.

   The APPLICATION_ROOT is the root of the url. It must have two segments and must be different for each database.

   Edit (or create) your server/instance/acts_ph4.conf

   APPLICATION_NAME="Acts Phase 4"
   APPLICATION_ROOT="/acts/ph4"
   BOOK="Acts"
   
   PGHOST="localhost"
   PGPORT="5432"
   PGDATABASE="acts_ph4"
   PGUSER="ntg"
   
   MYSQL_CONF="~/.my.cnf"
   MYSQL_GROUP="mysql"
   
   MYSQL_ECM_DB="ECM_ActsPh4"
   MYSQL_ATT_TABLES="Acts{n}GVZ"
   MYSQL_LAC_TABLES="Acts{n}GVZlac"
   
   MYSQL_VG_DB="VarGenAtt_ActPh4"
   MYSQL_LOCSTEM_TABLES="LocStemEdAct{n}"
   MYSQL_RDG_TABLES="RdgAct{n}"
   MYSQL_VAR_TABLES="VarGenAttAct{n}"
   MYSQL_MEMO_TABLE="Memo"
   
   MYSQL_NESTLE_DB="Nestle29"
   

3. Initialize the user management database and add an administrator user for the application server. You’ll need this user to login in the browser.

   Note

   This should not be the same username (and password) as the database user above!

   python3 -m scripts.cceh.mk_users -e <email> -u <username> -p <password> server/instance/_globals.conf
   

CBGM

1. Get the mysql database dumps from Münster (exercise left to the reader) and import them into mysql:

   mysql -D "ECM_ActsPh4"      < ECM_ActsPh4.dump
   mysql -D "VarGenAtt_ActPh4" < VarGenAtt_ActPh4.dump
   mysql -D "Nestle29"         < Nestle29.dump
   

2. Import the databases into postgres:

   python3 -m scripts.cceh.import -vvv server/instance/acts_ph4.conf
   python3 -m scripts.cceh.prepare -vvv server/instance/acts_ph4.conf
   

3. Run the CBGM process once.

   python3 -m scripts.cceh.cbgm -vvv server/instance/acts_ph4.conf
   

4. Setup cron to run the CBGM nightly:

   This step is optional. You may also run the cbgm script manually whenever you need it.

   Edit your user crontab

   crontab -e
   

   and put these lines into it:

   MAILTO=user@example.com
   
   13 02 * * * cd /home/ntg/prj/ntg/ntg && scripts/cceh/update_cbgm
   

Run Server

1. Run the application server:

   make server
   

Build and run client

1. Build and run the client

   cd client
   npm install
   cd ..
   make dev-server
   

Point your browser to http://localhost:5000/acts/ph4/