Skip to content

Host server setup

Jump to bottom
Irene Vagionakis edited this page Jun 15, 2021 · 21 revisions

Host server setup (step-by-step tutorial for Mac OS X / Unix)

1. Get a host server

Usually the host server is provided by your institution. If you have not been provided with a host server, you can get one for example by using the Amazon Web Services (AWS). AWS allow you to create also a free instance, which could be useful for testing purposes. On AWS:

  • Create a free EC2 instance, for example with OS Amazon Linux AMI 2; choose a region; set a security group with inbound rule with type SSH, protocol TCP, port range 22, source Anywhere and a security group with inbound rule with type HTTP, protocol TCP, port range 80, source Anywhere; enable SSH connections on your computer, or disable the Firewall.

  • Create a static IP: Elastic IP > allocate new address > associate to instance.

  • Create an SSH private key (key.pem) and save it wherever you want in your computer.

At this point you should have the following information:

  • user: your username for accessing the host server
  • IP: the host server IP
  • EFES: the name of your EFES folder; in this example we assume that it is located on the Desktop
  • key.pem: the name of your private key (if you need one)
  • path-to-folder-containing-key.pem: the path to the folder where the private key is saved (if you have one)

NB: If you are going to use a private key, before executing scp and ssh commands you will need to enter the computer folder in which you have saved the private key, by typing in the Terminal the command cd path-to-folder-containing-key.pem; also, you will need to replace each ssh with ssh -i key.pem, each scp -r with scp -ri key.pem and each rsync -re ssh with rsync -re 'ssh -i key.pem'.

2. Install Oracle Java Development Kit 8 (Oracle JDK 8) on the server and set JAVA_HOME

  • Download Oracle Java JDK 8 (in our case we downloaded jdk-8u251-linux-x64.tar.gz) from https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html and save it in your Desktop (NB: you will require an Oracle JDK license for using it for online distribution of the EFES site)

  • Execute the following commands in the Terminal:

    scp -r ~/Desktop/jdk-8u251-linux-x64.tar.gz user@IP:~

    ssh user@IP

    sudo mv jdk-8u251-linux-x64.tar.gz /opt/

    cd /opt

    sudo tar xzf jdk-8u251-linux-x64.tar.gz

    cd jdk1.8.0_251

    sudo update-alternatives --install /usr/bin/java java /opt/jdk1.8.0_251/bin/java 2

    sudo update-alternatives --config java

    sudo update-alternatives --install /usr/bin/jar jar /opt/jdk1.8.0_251/bin/jar 2

    sudo update-alternatives --set jar /opt/jdk1.8.0_251/bin/jar

    sudo update-alternatives --set javac /opt/jdk1.8.0_251/bin/javac

    sudo nano /etc/environment

    add JAVA_HOME="/opt/jdk1.8.0_251/" and then save and close (ctrl+O, enter, ctrl+X)

    export JAVA_HOME="/opt/jdk1.8.0_251/"

    export JRE_HOME="/opt/jdk1.8.0_251/jre"

    export PATH=$PATH:$JAVA_HOME/bin:$JRE_HOME/bin

    source /etc/environment

    echo $JAVA_HOME

3. Install Apache on the server and configure it as a proxy to Jetty

NB: this step may vary significantly depending on the used OS. In this case we have used Linux Debian 10. If you are using Linux CentOS, replace every occurrence of apache2 with httpd.

  • Install Apache and remove the default homepage index.html:

    sudo apt install apache2

    (or: sudo yum -y install httpd)

    sudo service apache2 start

    (or: sudo service httpd start)

    unlink /var/www/html/index.html

  • Enable the Apache modules for reverse proxying:

    cd /usr/lib/apache2/modules

    sudo a2enmod proxy_html

    sudo a2enmod proxy_http

    (or: sudo nano /etc/httpd/conf.modules.d/00-proxy.conf and uncomment LoadModule proxy_module modules/mod_proxy.so and LoadModule proxy_http_module modules/mod_proxy_http.so)

  • Create an admin password: sudo htpasswd -c /etc/apache2/.htpasswd admin

  • Edit the Apache configuration file to configure it as a proxy to Jetty and to restrict the access to the admin interface only to authorized users: sudo nano /etc/apache2/sites-available/000-default.conf

    (or: sudo nano /etc/httpd/httpd.conf; or: sudo nano /usr/local/etc/httpd/httpd.conf)

    change <VirtualHost *:80> in <VirtualHost *:*>

and add the following inside <VirtualHost *:*>:

ServerName localhost
ProxyVia Off
ProxyPreserveHost On
ProxyRequests Off
ProxyPass / http://localhost:9999/
ProxyPassReverse / http://localhost:9999/

<Location /admin>
    AuthType Basic
    AuthName "Restricted Content"
    AuthUserFile /etc/apache2/.htpasswd
    Require user admin
    Order allow,deny
    Allow from IP
    Satisfy Any
</Location>

<Location /solr>
    AuthType Basic
    AuthName "Restricted Content"
    AuthUserFile /etc/apache2/.htpasswd
    Require user admin
    Order allow,deny
    Allow from IP
    Satisfy Any
</Location>

<Location /openrdf-workbench>
    AuthType Basic
    AuthName "Restricted Content"
    AuthUserFile /etc/apache2/.htpasswd
    Require user admin
    Order allow,deny
    Allow from IP
    Satisfy Any
</Location>

If you need to restrict the access to the site to authorized users only during construction, add also the following:

<Location />
    AuthType Basic
    AuthName "Restricted Content"
    AuthUserFile /etc/apache2/.htpasswd
    Require user admin
    Order allow,deny
    Allow from IP
    Satisfy Any
</Location>

then save and close (ctrl+O, enter, ctrl+X)

sudo systemctl restart apache2

4. Copy or clone the EFES repository into the server

You can either copy the EFES repository from your computer (4a) or clone it from GitHub (4b).

4a. Copy the EFES repository into the server and move it into /var/www/html

scp -r ~/Desktop/EFES user@IP:~

ssh user@IP

sudo mv ~/EFES /var/www/html

4b. Clone the EFES repository from GitHub into /var/www/html

cd /var/www/html

sudo git init

sudo git clone https://github.com/EpiDoc/EFES.git (or the address of your fork/copy of the repository on GitHub)

5. If necessary, require permissions for executing build.sh and ant

cd /var/www/html/EFES

chmod 777 build.sh

cd /var/www/html/EFES/sw/ant/bin

chmod 777 ant

6. Execute build.sh to start the EFES site

ssh user@IP

cd /var/www/html/EFES

screen

./build.sh

ctrl+A, ctrl+D

Your EFES site is running now! You can now close the Terminal, because screen allows you to close it without stopping the process that is keeping the EFES site running.

NB: once the site is running, you will have to re-create a new Sesame repository through the Admin interface (Admin > Components > Sesame > Admin > New repository > create new repository with Type 'In Memory Store RDF Schema and Direct Type Hierarchy' and ID 'kiln'), right after typing http://localhost:9999/openrdf-sesame in the 'Change Server' field and clicking on 'Change'.

7. Stop the EFES site (if needed)

ssh user@IP

screen -r

ctrl+C

exit

8. Update the EFES site with rsync or git pull

8a. Update the EFES site with rsync

rsync -re ssh --progress --delete --exclude={'.git/','*.log','sw/jetty/temp'} ~/Desktop/EFES user@IP:~

ssh user@IP

screen -r

ctrl+C

rsync -r --progress --delete ~/EFES /var/www/html

./build.sh

ctrl+A, ctrl+D

8b. Update the EFES site with git pull (if cloned from GitHub)

ssh user@IP

screen -r

ctrl+C

sudo git pull

./build.sh

ctrl+A, ctrl+D

9. Set up a GitHub Action to update the site automatically from the GitHub repository (if cloned from GitHub)

  • In the GitHub repository settings go to 'Secrets' and add three new repository settings: HOST (the host server IP), USERNAME and PASSWORD
  • Go to the GitHub Actions section and set up a new workflow. This will create the file .github/workflows/main.yml, in which to put the following content:
name: CI
on:
  push:
    branches: [ master ]
  workflow_dispatch:
jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Update site
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          password: ${{ secrets.PASSWORD }}
          script: cd /var/www/html/EFES && sudo git pull

If you want also to automate the harvesting and indexing, at the end of the last line you can add && sudo curl http://IP/admin/rdf/harvest/all.html && sudo curl http://IP/admin/solr/index/all.html (replacing IP with the host server IP); if curl is not installed, you can install it with sudo apt-get install curl.

Clone this wiki locally