INSTALL

Installation for Gedafe and Perm 2.0
=====================================

The installation of Gedafe and Perm 2.0 can be done with the following
steps, numbered with digits from 1. to 10, and have been tested on Ubuntu
18.04 LTS.

Those steps beetween the digits and numbered with A. - Z. are steps for
installing Gedafe, Perm 2.0 and Ubuntu 18.04 on AWS.

Idea on AWS is to
* use the AWS Aurora PostgreSQL Database in serverless Modules
* create an golden Image with EC2, take a snapshot and create an AMI
* use and run the AMI Image with EC2 Spot Instances oder EC2


I. Initialize Create and Initialize Database
--------------------------------------------
 0. Install either the PostgreSQL Database on your host or use a managed
    PostgreSQL instance like AWS Aurora PostgreSQL or RDS PostgreSQL

 A1. Use the AWS Aurora PostgreSQL Serverless Edition

     * Select a possible region for using the *Serveless* Edition
       (Tested with eu-west-1 and us-east-1)

     * Create a Database (Database Cluster)

       Compatibility:     PostgreSQL 10.7 or above (tested)

       Name:              perm
       Master username:   ABCD_dbadmin (*NOT* perm_admin)
       Capacity Settings: min. 2, max. 4 Aurora capacity unit
       Security Group:    create a new SG "aurora-rds-sg"
       Pause:             Pause compute capacity after consecutive
                          minutes of inactivity 20 minutes
       VPC:               Create new VPC

     * Keep Database Connetion String
       Endpoint:    e.g. perm.cluster-abcdefghijkl.eu-west-1.rds.amazonaws.com
       Master-USER: masterusername
       Master-PWD:  masterpassword

    (* I have to Push the 'Create' Button twice, there seems be a CloudFormation
       error in the creation of the new VPC; after selecting the new created
       VPC after the first run / try, everything works as expected.)

 A2.  Fill the Database with the 'perm' database structure, code and functions

      * As the AWS Aurora PostgreSQL Serverless will not (maybe ever) have a
        public IP, I used this documented trick to fill the database structure.

        Follow this manual from AWS with the following adaptions for using
        PostgreSQL instead of MySQL:

        https://aws.amazon.com/getting-started/tutorials/configure-connect-serverless-mysql-database-aurora/

        * Install in the Cloud9 Environment PostgreSQL 10 client in the Cloud9
          terminal:

          * sudo apt update
          * sudo apt install postgresql-client-10

        * Upload the perm-db-setup.sql and perm-db-users-setup.sql in Cloud9 editor
          or download it directly in the Cloud9 terminal:

          # wget https://gitlab.com/prunux/perm/raw/master/perm-database/perm-db-setup.sql
          # wget https://gitlab.com/prunux/perm/raw/master/perm-database/perm-db-users-setup.sql

        * adapt usernames and passwords in perm-db-users-setup.sql

          * note the perm_master password, will be needed in the next step

        * Connect to the perm database cluster and "slurp" database structure
          and users:

          # psql -h perm.cluster-abcdefghijkl.eu-west-1.rds.amazonaws.com -U masterusername postgresql
          # > \i perm-db-setup.sql
          # > \i perm-db-users-setup.sql

        * check if there are no errors and if YES, DISCO DISCO PARTY PARTY (Step 1).

 *OR*

  1. Install the PostgreSQL Database on your Ubuntu 18.04:

     sudo apt update
     sudo apt install postgresql-10 postgresql-client-10

  2. Download perm-db-setup.sql and perm-db-users-setup.sql:

     wget https://gitlab.com/prunux/perm/raw/master/perm-database/perm-db-setup.sql
     wget https://gitlab.com/prunux/perm/raw/master/perm-database/perm-db-users-setup.sql

  3. adapt usernames and passwords in perm-db-users-setup.sql

     * note the perm_master password, will be needed in the next step

  4. Connect to the perm database cluster and "slurp" database structure and
     users:

     sudo su - postgres
     psql
     > \i perm-db-setup.sql
     > \i perm-db-users-setup.sql



II. Webserver Ubuntu 18.04 with perm and gedafe code
---------------------------------------------------

 1. Launch Instance with Ubuntu 18.04

   A1. Launch an Instance with Ubuntu 18.04 on AWS

      * Create and Activate AWS Account
        https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/

      * Create an EC2 Instance
        https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/launching-instance.html

      * Don't forget to create a security group with Port HTTP (80), and HTTPS (443)
        and SSH (22) for the EC2 instance

 2. Login to Ubuntu 18.04 instance, gain super rights and download gedafe and
    perm checkouts

    ssh -i perm-test.pem ubuntu@MYINSTANCE.MYDOMAIN
    # e.g. ssh -i perm-test.pem ubuntu@ec2-54-171-159-0.eu-west-1.compute.amazonaws.com

    cd /tmp
    wget https://gitlab.com/prunux/gedafe/-/archive/master/gedafe-master.tar.gz
    wget https://gitlab.com/prunux/perm/-/archive/master/perm-master.tar.gz
    cd -

 3. create a 'gedafe' and 'perm' linux user, keep user account passwords (and
    add your ssh key)

    sudo adduser --uid 1001 gedafe
    # Full Name: Gedafe User

    sudo adduser --uid 1002 perm
    # Full Name: Perm User

    # keep account password in your password safe

    # and add if wished your SSH-KEY:
    # #  ssh-copy-id -i perm-test.pem perm@MYINSTANCE.MYDOMAIN
    # #  ssh-copy-id -i perm-test.pem gedafe@MYINSTANCE.MYDOMAIN
    #

 4. extract gedafe-code to /home/gedafe

    sudo tar xzvf /tmp/gedafe-master.tar.gz -C /home/gedafe
    sudo mv /home/gedafe/gedafe-master/* /home/gedafe/
    sudo rm /home/gedafe/gedafe-master/.gitignore
    sudo rmdir /home/gedafe/gedafe-master/
    sudo chown -Rh gedafe:gedafe /home/gedafe

 5. extract perm-code to /home/perm

    sudo tar xzvf /tmp/perm-master.tar.gz -C /home/perm
    sudo mv /home/perm/perm-master/* /home/perm/
    sudo rmdir /home/perm/perm-master/
    sudo chown -Rh perm:perm /home/perm

 6. Update Ubuntu 18.04 system and install additional necessary packages for
    running perm and compiling necessary perl modules

    sudo apt update
    sudo apt upgrade -y

    sudo apt install -y postgresql-client-10

    sudo apt install -y apache2
    sudo apt install -y libapache2-mod-fcgid

    sudo apt install -y libcgi-fast-perl
    sudo apt install -y libdbi-perl
    sudo apt install -y libdbd-pg-perl
    sudo apt install -y libyaml-libyaml-perl

 7. Install certbot

    sudo apt-get update
    sudo apt-get install software-properties-common
    sudo add-apt-repository -y universe
    sudo add-apt-repository -y ppa:certbot/certbot
    sudo apt-get update

    sudo apt-get install -y certbot python-certbot-apache

8.  Preconfigure Apache

    sudo a2enmod headers
    sudo a2enmod rewrite
    sudo a2enmod ssl
    sudo a2enmod userdir
    sudo systemctl restart apache2

 9. adapt apache configuration and configure domain

    sudo cp /home/perm/etc/apache2/sites-available/mysubdomain.mydomain.mytld.conf /etc/apache2/sites-available/mysubdomain.mydomain.mytld.conf
    sudo cp -a /home/perm/public_html/images /var/www/images

    # change MY.. to your domain name!
    sudo mv /etc/apache2/sites-available/mysubdomain.mydomain.mytld.conf /etc/apache2/sites-available/MYSUBDOMAIN.MYDOMAIN.MYLTD.conf

    # edit and configure correct domain name (needed also for TLS)
    sudo vim /etc/apache2/sites-available/MYSUBDOMAIN.MYDOMAIN.MYLTD.conf

    # disable default webpage
    sudo a2dissite 000-default.conf
    sudo systemctl reload apache2

    # enable apache perm website
    sudo a2ensite MYSUBDOMAIN.MYDOMAIN.MYLTD.conf
    # check config and if okay, restart apache
    sudo apache2ctl configtest
    sudo systemctl reload apache2

    # enable TLS and letsencrypt
    sudo certbot --apache -d MYSUBDOMAIN.MYDOMAIN.MYLTD -m important.emailadress@MYDOMAIN.MYLTD --agree-tos -n

    # check config and if okay, restart apache
    sudo apache2ctl configtest
    sudo systemctl reload apache2

10. adopt database connection to correct and initialized database (see also
    part I. above)

    sudo vim /home/perm/public_html/db_config.yaml

11. enable gedafed systemd service at startup

    sudo cp /home/gedafe/etc/systemd/system/gedafed.service /etc/systemd/system/
    sudo systemctl daemon-reload
    sudo systemctl start gedafed.service
    sudo systemctl status gedafed.service
    sudo systemctl enable gedafed.service
    sudo systemctl status gedafed.service

III. AWS handling
-----------------



IV. HISTORY
-----------


sudo apt install etckeeper


    7. install Perl Modules

    su - gedafe
    cd /home/gedafe/thirdparty
    ./build_gedafe.sh


V. NOTES
--------

License
-------
    Perm is a permission and access management system with RDMS.
    Copyright (C) 2015-2019, Stiftung 3FO, CH-4600 Olten
    Copyright (C) 2015-2019, Forem AG, CH-4600 Olten
    Copyright (C) 2015-2019, Roman Plessl (prunux.ch)

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

Copyright
---------

    Copyright (c) 2015-2019 Stiftung 3FO, Olten, All rights reserved.
    Copyright (c) 2015-2019 Plessl + Burkhardt GmbH, All rights reserved.

    This database design and code was donated and paid by

        Stiftung 3FO, Belchenstrasse 7, CH-4600 Olten and
        Forem AG, Belchenstrasse 7, CH-4600 Olten

Authors
-------

   Roman Plessl