Skip to content

APMIS Server Set up, Database and System Configuration Documentation

Jump to bottom Edit New page
Segun edited this page Apr 17, 2023 · 1 revision

Installing an APMIS Server

Note: This guide explains how to set up a APMIS server on Linux and Windows systems, the latter only being intended for usage on development systems. Please also note that certain parts of the setup script will not be executed on Windows.

Content

Related

Prerequisites

Java 11

Download and install the Java 11 JDK (not JRE) for your operating system. We suggest using the Zulu OpenJDK.

Linux

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 0xB1998361219BD9C9
sudo apt-add-repository 'deb https://repos.azul.com/zulu/deb/ stable main'
sudo apt-get update
sudo apt-get install zulu11

Windows

For testing and development environments we suggest to download and run the installer of the Java 11 JDK for 32 or 64 bit client systems (depending on your system). You can check your Java version from the shell/command line using: java -version.

Postgres Database

sudo apt-get install libpq-dev
sudo apt-get install postgresql-server-dev-all
sudo apt install pgxnclient
#Check for GCC:
gcc --version # and install if missing
sudo pgxn install temporal_tables
# The packages can be removed afterward

APMIS Server

Get the latest APMIS build by downloading the ZIP archive from the latest release on GitHub: https://github.com/xlg8/APMIS-Project/releases/latest

Install on Linux

Unzip the archive, copy/upload its contents to /root/deploy/sormas/$(date +%F) and make the setup script executable (as root user).

sudo su
mkdir /root/deploy/sormas
cd /root/deploy/sormas
APMIS_VERSION=1.y.z
wget https://github.com/xlg8/APMIS-Project/releases/download/v${APMIS_VERSION}/sormas_${APMIS_VERSION}.zip
unzip sormas_${APMIS_VERSION}.zip
mv deploy/ $(date +%F)
rm sormas_${APMIS_VERSION}.zip
chmod +x $(date +%F)/server-setup.sh

Install on Windows

  • Download & install Git for Windows. This will provide a bash emulation that you can use to run the setup script: https://gitforwindows.org/
  • Unzip the ZIP archive (e.g. into you download directory)
  • Open Git Bash and navigate to the setup sub-directory

Post-Installation Configuration

  • Optional: Open server-setup.sh in a text editor to customize the install paths, database access and ports for the server. The default ports are 6080 (HTTP), 6081 (HTTPS) and 6048 (admin). Important: Do not change the name of the database user. The pre-defined name is used in the statements executed in the database.
  • Set up the database and a Payara domain for APMIS by executing the setup script: sudo -s ./server-setup.sh Press enter whenever asked for it
  • IMPORTANT: Make sure the script executed successfully. If anything goes wrong you need to fix the problem (or ask for help), then delete the created domain directory and re-execute the script.
  • IMPORTANT: Adjust the APMIS configuration for your country in /opt/domains/sormas/sormas.properties
  • Adjust the logging configuration in /opt/domains/sormas/config/logback.xml based on your needs (e.g. configure and activate email appender)
  • Linux: Update the APMIS domain

Web Server Setup

Apache Web Server

Note: This is not necessary for development systems. When you are using APMIS in a production environment you should use a http server like Apache 2 instead of putting the Payara server in the first line. Here are some things that you should do to configure the Apache server as a proxy:

Activate all needed modules:

a2enmod ssl
a2enmod rewrite
a2enmod proxy
a2enmod proxy_http
a2enmod headers

Create a new site /etc/apache2/sites-available/your.apmis.server.url.conf (e.g. apmis.org.conf).

Force SSL secured connections: redirect from http to https:

<VirtualHost *:80>
        ServerName your.apmis.server.url
        RewriteEngine On
        RewriteCond %{HTTPS} !=on
        RewriteRule ^/(.*) https://your.apmis.server.url/$1 [R,L]
</VirtualHost>
<IfModule mod_ssl.c>
<VirtualHost *:443>
        ServerName your.apmis.server.url
        ...
</VirtualHost>
</IfModule>

Configure logging:

ErrorLog /var/log/apache2/error.log
LogLevel warn
LogFormat "%h %l %u %t \"%r\" %>s %b _%D_ \"%{User}i\"  \"%{Connection}i\"  \"%{Referer}i\" \"%{User-agent}i\"" combined_ext
CustomLog /var/log/apache2/access.log combined_ext

SSL key config:

SSLEngine on
SSLCertificateFile    /etc/ssl/certs/your.apmis.server.url.crt
SSLCertificateKeyFile /etc/ssl/private/your.apmis.server.url.key
SSLCertificateChainFile /etc/ssl/certs/your.apmis.server.url.ca-bundle

# disable weak ciphers and old TLS/SSL
SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE$
SSLHonorCipherOrder off

Add a proxy pass to the local port:

ProxyRequests Off
ProxyPass /sormas-ui http://localhost:6080/sormas-ui
ProxyPassReverse /sormas-ui http://localhost:6080/sormas-ui
ProxyPass /sormas-rest http://localhost:6080/sormas-rest
ProxyPassReverse /sormas-rest http://localhost:6080/sormas-rest

Configure security settings:

Header always set X-Content-Type-Options "nosniff"
Header always set X-Xss-Protection "1; mode=block"
# Disable Caching
Header always set Cache-Control "no-cache, no-store, must-revalidate, private"
Header always set Pragma "no-cache"

Header always set Content-Security-Policy \
        "default-src 'none'; \
        object-src 'self'; \
        script-src 'self' 'unsafe-inline' 'unsafe-eval'; \
        connect-src https://fonts.googleapis.com https://fonts.gstatic.com 'self'; \
        img-src *; \
        style-src 'self' https://fonts.googleapis.com 'unsafe-inline'; \
        font-src https://fonts.gstatic.com 'self'; \
        frame-src 'self'; \
        worker-src 'self'; \
        manifest-src 'self'; \
        frame-ancestors 'self'

# The Content-Type header was either missing or empty.
# Ensure each page is setting the specific and appropriate content-type value for the content being delivered.
AddType application/vnd.ms-fontobject    .eot
AddType application/x-font-opentype      .otf
AddType image/svg+xml                    .svg
AddType application/x-font-ttf           .ttf
AddType application/font-woff            .woff

Activate output compression (very important!):

<IfModule mod_deflate.c>
        AddOutputFilterByType DEFLATE text/plain text/html text/xml
        AddOutputFilterByType DEFLATE text/css text/javascript
        AddOutputFilterByType DEFLATE application/json
        AddOutputFilterByType DEFLATE application/xml application/xhtml+xml
        AddOutputFilterByType DEFLATE application/javascript application/x-javascript
        DeflateCompressionLevel 1
</IfModule>

Provide the android apk:

Options -Indexes
AliasMatch "/downloads/sormas-(.*)" "/var/www/sormas/downloads/sormas-$1"

For the Apache 2 security configuration we suggest the following settings (/etc/apache2/conf-available/security.conf):

ServerTokens Prod
ServerSignature Off
TraceEnable Off

Header always set Strict-Transport-Security "max-age=15768000; includeSubDomains; preload"
Header unset X-Frame-Options
Header always set X-Frame-Options SAMEORIGIN
Header unset Referrer-Policy
Header always set Referrer-Policy "same-origin"
Header edit Set-Cookie "(?i)^((?:(?!;\s?HttpOnly).)+)$" "$1;HttpOnly"
Header edit Set-Cookie "(?i)^((?:(?!;\s?Secure).)+)$" "$1;Secure"

Header unset X-Powered-By
Header unset Server
  • In case you need to update the site config while the server is running, use the following command to publish the changes without the need for a reload:
apache2ctl graceful

Firewall

  • The server should only publish the ports that are needed. For APMIS this is port 80 (HTTP) and 443 (HTTPS). In addition you will need the SSH port to access the server for admin purposes.
  • We suggest to use UFW (Uncomplicated Firewall) which provides a simple interface to iptables:
sudo apt-get install ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

Postfix Mail Server

Install postfix and mailutils

apt install aptitude
aptitude install postfix
-> choose "satelite system"
apt install mailutils

Configure your system

nano /etc/aliases
-> add "root: [email protected]"
nano /opt/domains/sormas/config/logback.xml
-> make sure "EMAIL_ERROR" appender is active and sends out to your email address

Testing the Server Setup

Use SSL Labs to test your server security config: https://www.ssllabs.com/ssltest

Installing an APMIS Server for Development

**Note: This guide explains how to configure a APMIS server on Linux and Windows systems for development.

Content

Related

Prerequisites

Java 11

See Installing Java

APMIS just recently moved to Java 11. We still need to support Java 8 for a transition period. Therefore, please just use Java 8 language features for now.

Ant

Download and install Ant, it can be done from Ant site or with packages from your Linux distribution.

Postgres Database

See Installing Postgresql

APMIS Server

Install you own Payara server (see Installing an APMIS Server) or run bash ./server-setup-dev-docker.sh

This script will download Payara (if needed) and install APMIS in the Payara server.

You can edit this script to change paths and ports.

Other steps :

  • IMPORTANT: Adjust the APMIS configuration for your country in /opt/domains/sormas/sormas.properties
  • Adjust the logging configuration in ${HOME}/opt/domains/sormas/config/logback.xml based on your needs (e.g. configure and activate email appender)
  • Build and deploy applications (ear and war) with you IDE.

VAADIN Debug Mode

To enable VAADIN Debug Mode, go to sormas-ui/src/main/webapp/WEB-INF/web.xml and set productionMode to false. Make sure not to commit your changes to these files, for example by using .gitignore. To access the debug Window, got to /sormas-ui/?debug. You may need to log in as admin once first.

Other components

See Installing an APMIS Server

Updating an APMIS Server

APMIS releases starting from 1.21.0 contain a script that automatically updates and deploys the server. If you are using an older version and therefore need to do a manual server update, please download the 1.21.0 release files and use the commands specified in the server-update.sh script.

Preparations

Note: You can skip this step if you've just set up your APMIS server and have already downloaded the latest release.

  • Get the latest release files (deploy.zip) from https://github.com/xlg8/APMIS-Project/releases/latest
  • Unzip the archive and copy/upload its contents to /root/deploy/sormas/$(date +%F) 
    cd /root/deploy/sormas
APMIS_VERSION=1.y.z
wget https://github.com/xlg8/APMIS-Project/releases/download/v${APMIS_VERSION}/sormas_${APMIS_VERSION}.zip
unzip sormas_${APMIS_VERSION}.zip
mv deploy/ $(date +%F)
rm sormas_${APMIS_VERSION}.zip

Automatic Server Update

  • Navigate to the folder containing the unzipped deploy files: cd /root/deploy/sormas/$(date +%F)
  • Make the update script executable: chmod +x server-update.sh
  • Optional: Open server-update.sh in a text editor to customize the values for e.g. the domain path or the database name. You only need to do this if you used custom values while setting up the server.
  • Execute the update script and follow the instructions: ./server-update.sh
  • If anything goes wrong, open the latest update log file (by default located in the "update-logs" folder in the domain directory) and check it for errors.

Restoring the Database

If anything goes wrong during the automatic database update process when deploying the server, you can use the following command to restore the data:

pg_restore --clean -U postgres -Fc -d sormas_db sormas_db_....dump

Default Logins

These are the default users for most user roles, intended to be used on development or demo systems. In all cases except the admin user, the username and password are identical. Make sure to deactivate them or change the passwords on productive systems.

Admin

Username: admin Password: sadmin

Web users

Surveillance Supervisor: SurvSup Case Supervisor: CaseSup Contact Supervisor: ContSup Point of Entry Supervisor: PoeSup Laboratory Officer: LabOff Event Officer: EveOff National User: NatUser National Clinician: NatClin

Mobile app users

Surveillance Officer: SurvOff Hospital Informant: HospInf Point of Entry Informant: PoeInf

Troubleshooting

Problem: Login fails

Check that the users table does have a corresponding entry. If not, the database initialization that is done when deploying sormas-ear.ear probably had an error.

Problem: Server is out of memory

Old servers were set up with a memory size of less than 2048MB. You can change this using the following commands:

/opt/payara-172/glassfish/bin/asadmin --port 6048 delete-jvm-options -Xmx512m
/opt/payara-172/glassfish/bin/asadmin --port 6048 delete-jvm-options -Xmx1024m
/opt/payara-172/glassfish/bin/asadmin --port 6048 create-jvm-options -Xmx2048m

Alternative: You can edit the settings directly in the domain.xml in the config directory of the APMIS domain. Just search for Xmx - there should be two entries that need to be changed.

Add a custom footer
Add a custom sidebar
Clone this wiki locally