Note: This guide explains how to set up a SORMAS 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.
- Installing a SORMAS Server
Download and install the Java 11 JDK (not JRE) for your operating system. We suggest using the Zulu OpenJDK.
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 zulu11For 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.
- Install PostgreSQL (currently 14 to 15) on your system (manuals for all OS can be found here: https://www.postgresql.org/download)
- Set max_connections = 288 and max_prepared_transactions = 256 (at least, sum of all connection pools) in
postgresql.conf(e.g./etc/postgresql/14.0/main/postgresql.conf;C:/Program Files/PostgreSQL/14.0/data) - make sure the property is uncommented and restart the service to apply the changes. - Install the "temporal tables" extension for Postgres (https://github.com/arkhipov/temporal_tables)
- Windows: Download the latest version for your Postgres version:
- https://github.com/arkhipov/temporal_tables/releases/latest, then copy the DLL from the project into the PostgreSQL's lib directory and the .sql and .control files into the directory share\extension.
- Linux (see https://github.com/arkhipov/temporal_tables#installation)
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
- Add the PostgreSQL path (/etc/PostgreSQL/10/bin) to Environment Variables
- Windows: Download the latest version for your Postgres version:
Get the latest SORMAS build by downloading the ZIP archive from the latest release on GitHub: https://github.com/sormas-foundation/SORMAS-Project/releases/latest
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 -p /root/deploy/sormas
cd /root/deploy/sormas
SORMAS_VERSION=1.y.z
wget https://github.com/sormas-foundation/SORMAS-Project/releases/download/v${SORMAS_VERSION}/sormas_${SORMAS_VERSION}.zip
unzip sormas_${SORMAS_VERSION}.zip
mv deploy/ $(date +%F)
rm sormas_${SORMAS_VERSION}.zip
chmod +x $(date +%F)/server-setup.sh- 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
You can configure the audit logger of SORMAS by providing a Logback configuration file and setting the audit.logger.config property accordingly. An example is provided in sormas-base/setup/audit-logback.xml. Not specifying a value for the property will effectively disable the audit log.
- Optional: Open
server-setup.shin 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 predefined name is used in the statements executed in the database. - Set up the database and a Payara domain for SORMAS by executing the setup script:
sudo -s ./server-setup.shPress 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 SORMAS configuration for your country in /opt/domains/sormas/sormas.properties
- Adjust the logging configuration in
/opt/domains/sormas/config/logback.xmlbased on your needs (e.g. configure and activate email appender) - Linux: Update the SORMAS domain
Note: SORMAS also comes with a basic auth mechanism using an JEE authentication realm. This authentication mechanism should only be used for development environments. For production environments always use the keycloak authentication mechansim. See Authentication & Authorization.
Keycloak can be set up in two ways:
- as a Docker container (for just using Keycloak approach)
- as a Standalone installation (for doing development in Keycloak like themes, SPIs)
To be done only in the situation when SORMAS is already installed on the machine as a standalone installation.
For complete Docker setup see the SORMAS-Docker repository.
Prerequisites
- SORMAS Server is installed
- PostgreSQL is installed
- Docker is installed
- Open and edit
sormas-base/setup/keycloak/keycloak-setup.shwith your system's actual values (on Windows use Git Bash).
Setup
- Run
sormas-base/setup/keycloak/keycloak-setup.sh - Update
sormas.propertiesfile in the SORMAS domain with the propertyauthentication.provider=KEYCLOAK - Change in keycloak administration console the client ID for
sormas-statsandsormas-uifromhttpstohttp
Prerequisites
- SORMAS Server is installed
- PostgreSQL is installed
Setup
Setting Keycloak up as a standalone installation as described in the Getting started section of the official guide
- Make sure to configure Keycloak with PostgreSQL Database
- Set up an Admin User
- Copy the
themesfolder content to${KEYCLOAK_HOME}/themesas described here - Deploy the
sormas-keycloak-service-provideras described here - Update the
sormas-base/setup/keycloak/SORMAS.jsonfile by replacing the following placeholders:${SORMAS_SERVER_URL},${KEYCLOAK_SORMAS_UI_SECRET},${KEYCLOAK_SORMAS_BACKEND_SECRET},${KEYCLOAK_SORMAS_REST_SECRET} - Create the SORMAS Realm by importing
sormas-base/setup/keycloak/SORMAS.jsonsee Create a New Realm - Update the
sormas-*clients by generating new secrets for them - Update the realm's email settings to allow sending emails to users
To update the SORMAS Server run the following commands:
${ASADMIN} set-config-property --propertyName=payara.security.openid.clientSecret --propertyValue=${KEYCLOAK_SORMAS_UI_SECRET} --source=domain
${ASADMIN} set-config-property --propertyName=payara.security.openid.clientId --propertyValue=sormas-ui --source=domain
${ASADMIN} set-config-property --propertyName=payara.security.openid.scope --propertyValue=openid --source=domain
${ASADMIN} set-config-property --propertyName=payara.security.openid.providerURI --propertyValue=http://localhost:${KEYCLOAK_PORT}/keycloak/auth/realms/SORMAS --source=domain
${ASADMIN} set-config-property --propertyName=sormas.rest.security.oidc.json \
--propertyValue="{\"realm\":\"SORMAS\",\"auth-server-url\":\"http://localhost:${KEYCLOAK_PORT}/auth\",\"ssl-required\":\"external\",\"resource\":\"sormas-rest\",\"credentials\":{\"secret\":\"${KEYCLOAK_SORMAS_REST_SECRET}\"},\"confidential-port\":0,\"principal-attribute\":\"preferred_username\",\"enable-basic-auth\":true}" \
--source=domain
${ASADMIN} set-config-property --propertyName=sormas.backend.security.oidc.json --propertyValue="{\"realm\":\"SORMAS\",\"auth-server-url\":\"http://localhost:${KEYCLOAK_PORT}/auth/\",\"ssl-required\":\"external\",\"resource\":\"sormas-backend\",\"credentials\":{\"secret\":\"${KEYCLOAK_SORMAS_BACKEND_SECRET}\"},\"confidential-port\":0}" --source=domainwhere:
${ASADMIN}- represents the location to${PAYARA_HOME}\bin\asadmin${KEYCLOAK_PORT}- the port on which keycloak will run${KEYCLOAK_SORMAS_UI_SECRET}- is the secret generated in Keycloak for thesormas-uiclient${KEYCLOAK_SORMAS_REST_SECRET}- is the secret generated in Keycloak for thesormas-restclient${KEYCLOAK_SORMAS_BACKEND_SECRET}- is the secret generated in Keycloak for thesormas-backendclient
Then update sormas.properties file in the SORMAS domain with the property authentication.provider=KEYCLOAK
after setting up Keycloak as one of the described options above
In case Keycloak is set up alongside an already running instance of SORMAS, these are the steps to follow to make sure already existing users can access the system:
- Manually create an admin user in Keycloak for the SORMAS realm Creating a user (username has to be the same as admin's username in SORMAS)
- If your server is not using SSL (e.g. because it's a development environment), you need to update the Root URL of the sormas-ui client in the SORMAS realm to use http instead of https
- Login to SORMAS and trigger the Sync Users button from the Users page
- This will sync users to Keycloak keeping their original password - see SORMAS Keycloak Service Provider for more information about this
The synchronization of users between SORMAS and Keycloak is can be done in two ways:
from SORMAS to Keycloak or from Keycloak to SORMAS depending on how the AUTH_PROVIDER_TO_SORMAS_USER_SYNC feature is configured.
By default, the AUTH_PROVIDER_TO_SORMAS_USER_SYNC feature is disabled so the synchronization happens from SORMAS to Keycloak.
An automatic synchronization happens when a user is created/changed/deleted in SORMAS,
and there is another way to trigger this manually by an admin on the users page meaning the users are managed in SORMAS.
If the feature is enabled, the synchronization is done from Keycloak to SORMAS.
In order to make this feature work you also need to configure the authentication.provider.syncedNewUserRoleconfiguration property in the sormas.properties file
to the name of the role that you want to be assigned to the new users coming from Keycloak.
This feature doesn't allow changing the users in SORMAS, except their roles and language, so users will be managed in keycloak. The synchronization is done automatically each day at night, or manually by an admin on the users page when needed.
More about the default configuration and how to customize can be found here Keycloak
Note: This is not necessary for development systems. When you are using SORMAS 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 headersCreate a new site /etc/apache2/sites-available/your.sormas.server.url.conf (e.g. sormas.org.conf).
Force SSL secured connections: redirect from http to https:
<VirtualHost *:80>
ServerName your.sormas.server.url
RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteRule ^/(.*) https://your.sormas.server.url/$1 [R,L]
</VirtualHost>
<IfModule mod_ssl.c>
<VirtualHost *:443>
ServerName your.sormas.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.sormas.server.url.crt
SSLCertificateKeyFile /etc/ssl/private/your.sormas.server.url.key
SSLCertificateChainFile /etc/ssl/certs/your.sormas.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- The server should only publish the ports that are needed. For SORMAS 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 enableapt install aptitude
aptitude install postfix
-> choose "satelite system"
apt install mailutilsnano /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 addressUse SSL Labs to test your server security config: https://www.ssllabs.com/ssltest
In order to enable disease network diagrams in the contact dashboard, R and several extension packages are required.
Then the Rscript executable has to be configured in the sormas.properties file.
This can be conveniently accomplished by executing the R setup script from the SORMAS ZIP archive (see SORMAS Server):
- If the SORMAS installation has been customized,
r-setup.shthe install paths may have to be adjusted accordingly with a text editor. - Execute R setup script and follow its instructions.
chmod +x r-setup.sh
./r-setup.shTo be able to communicate with other SORMAS instances, there are some additional steps which need to be taken, in order to set
up the certificate and the truststore. Please see the related guide for detailed instructions regarding SORMAS to SORMAS setup.
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.
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 -Xmx2048mAlternative: You can edit the settings directly in the domain.xml in the config directory of the SORMAS domain. Just search for Xmx - there should be two entries that need to be changed.