Updated 2022-08-29

Table of contents

  1. Introduction
  2. Deployment models
    1. Stand-alone
    2. Dedicated
    3. Portable
  3. Technical requirements
    1. Server
    2. Clients
  4. Installation
    1. On Windows Server
    2. On a Linux server
  5. First access to REI3
  6. Configuration
    1. SSL certificates
  7. General administration
    1. Maintenance mode
    2. Builder mode
    3. Authentication and authorization
    4. Connecting logins to data sets
    5. Authentication and authorization via LDAP
  8. Manage applications
  9. Backup and recovery
    1. Files
    2. Database
  10. Updates
    1. Platform updates
  11. Clustering and system performance
  12. Cloud operations

Introduction

This is the documentation for deploying, configurating and operating the REI3 application platform. It assumes some system administration knowledge for the target infrastructure (Windows Server or Linux). Once running, administrators can deploy REI3 applications from online or local repositories in infrastructures with or without internet access.

Deployment models

To work within various customer environments, multiple deployment models are available for the REI3 platform; these are listed below in detail. Installation and configuration instructions follow afterwards.

Stand-alone

This model was created for small and medium size installations (~250 users) and is available for Windows Server. The stand-alone deployment has almost no external dependencies. It is the recommended model for organizations with smaller IT teams as it requires little management.

When running stand-alone, REI3 includes and manages its own internal database with full backups being configurable from within the REI3 admin user interface. This deployment model does currently not support incremental backups; a limitation for large instances as full backups take longer to complete.

It is always possible to migrate from stand-alone to the dedicated deployment model.

Dedicated

In this model REI3 runs as an application separate from its database system. This is recommended for large instances or when an organization has a database team onhand. This version can be deployed on Linux and Windows servers.

Running this model, REI3 will require a separate PostgreSQL database system and will not manage any database backups.

Portable

An option for development, demo and test instances. With the portable version, REI3 can be started on Windows servers or clients directly without any setup. Like the stand-alone model, the portable version includes its own database. It is not recommended to run anything productive from a portable instance.

Technical requirements

Server

To run REI3 the following requirements must be met:

  • Operating system (one of them)
    • Linux server (tested on Debian, CentOS and Ubuntu Server)
    • Windows Server 2016 or later
    • Not officially supported but can be used:
      • Darwin
      • FreeBSD
  • Processor
    • Intel or AMD processors (64bit), multiple cores provide better performance
    • ARM processors are not officially supported but were successfully used for REI3 in the past
  • Memory
    • 4+ GB (medium size installation, ~250 users)
  • Disk space
    • 500 MB for REI3 itself
    • 20+ GB for the database and file uploads (scales with use)
  • Software
    • Microsoft Visual C++ 2015 (or newer - Windows Server only)
  • Databases (dedicated deployment only)
    • PostgresSQL 13.0 database (or newer), UTF8 encoded, with full permissions

Clients

To access a running REI3 instance, any modern browser can be used, like Firefox, Chrome or Safari. This includes mobile browsers. REI3 uses modern web standards; it does not support Internet Explorer.

Installation

On Windows Server

REI3 comes with a graphical installer for Windows Server. The installer supports both stand-alone and dedicated deployment models.

  • Stand-alone: After following the installer, REI3 can be started immediately.
  • Dedicated: After the installation, database connection details for an empty PostgreSQL database must be entered into the configuration file config.json. The file config.json is located inside the chosen application directory. The database user must have full permissions for the chosen database.

Independent of deployment model, REI3 is handled as a Windows service and can be started with the service manager (command: service.msc). REI3 will write to the Windows application log, should the service not start correctly.

On a Linux server

For Linux servers, REI3 is available as a compressed archive with pre-compiled binary. The installation steps are:

  1. Extract the REI3 archive file to a location of your choice (/opt/rei3/ for example).
  2. Make the file r3 executable (chmod u+x r3).
  3. Copy the file config_template.json to config.json - keep it in the same directory as the r3 executable.
  4. Add connection details to an empty PostgreSQL database to config.json. The database user must have full permissions for the chosen database.
  5. Register REI3 with your service manager by running sudo r3 -install.
  6. Start the REI3 service, with systemctl start rei3 for example.

If the service does not start, REI3 writes to syslog.

First access to REI3

When running, REI3 is by default reachable on port 443. You can use any modern browser to access REI3 locally at https://localhost/ or from the network, given a configured firewall. During installation, a single admin user is created; username and password are both 'admin'.

After login, an admin user can access the admin panel to manage users, install applications, access system logs and so on. The default password should be changed immediately.

Configuration

REI3s core configuration can be changed within its configuration file (config.json), which is located in the chosen REI3 installation directory. Setting file paths, web server port and database connection details is straightforward. Changes are applied when the application service restarts. Special configuration options and certification management is explained separately.

SSL certificates

During installation, REI3 creates a self-signed certificate to allow encrypted access to the application. It is not recommended to keep this certificate. If at all possible, a properly signed certificate should be provided for REI3 to ensure secure communication with trust between clients and server.

We can offer support for setting up necessary infrastructure; it is however dependent on your organization to manage certificates. Cloud based offerings for REI3 can include certification services.

General administration

After configuration, basically all administrative tasks are executed via the admin user interface inside the main REI3 web application. Any user defined as 'admin' has full access to these features.

Maintenance mode

To execute deep system changes safely, a separate operation mode is available, called 'maintenance mode'. When enabled, all non-admin users are automatically logged off from the system; new logins are also rejected from non-admin users.

In maintenance mode, applications may be installed, configured and deleted. Please be aware that deleting applications will permanently delete all corresponding data from the system. This is irreversable without current, functional backups.

Builder mode

When the maintenance mode is active, Builder mode can also be enabled. This gives admin users access to the integrated, graphical application builder utility, called 'Builder' for short. The Builder is a powerful tool. All REI3 applications are exclusively created and changed via the Builder. Please be aware that changing applications has permanent consequences up to and including data loss. Do not attempt to use the Builder in any productive instance. For testing or developing applications, a separated instance should be used. The portable version makes this easy on Windows clients. On Linux a separated application service, accessing a separate database, serves the same purpose.

Authentication and authorization

Users are authenticated in REI3 via defined login names and passwords. New logins can be created at will; there are no limits except that login names need to be unique. To grant access, application roles need to be assigned to logins. Roles work cumulatively; the more roles a login is assigned to, the more permissions are granted. Options for password complexity are available in the admin user interface.

Connecting logins to data sets

Some applications relate data sets to logged in users to facilitate workflows. One example is the application 'Organizations', which connects logins to employees. This connection can then be used by all applications building on 'Organizations'. Other entities can be connected to logins as well, like connecting logins to customer accounts. Please refer to the corresponding application help pages to learn more.

Authentication and authorization via LDAP

REI3 hosts its own, internal authentication backend. To integrate into existing infrastructures, REI3 can utilize LDAP services to offer:

  • LDAP-Authentication: User accounts are imported from LDAP regularly to create local logins. Login credentials are then checked live against the LDAP.
    • Using multiple LDAD connections (or mixing local with LDAP logins), can cause name duplications to occur. The LDAP connection can be configured to use email addresses or other attributes for login names instead.
    • Microsoft AD only: When a user account is disabled, active sessions are automatically closed during the next LDAP import.
  • LDAP-Authorization: By reading group memberships, application roles can automatically be assigned to logins.
    • Microsoft AD only: Nested group memberships are automatically resolved.

Manage applications

To get use out of REI3, applications need to be installed. To manage applications, the maintenance mode must be enabled first.

Applications are installed via the admin user interface. They can be retrieved from multiple sources:

  • Official repository: Pre-installed repository for official REI3 applications. Internet access is required to access this online service.
  • Local repository: For organizations running multiple REI3 instances and/or needing full control over all releases. A repository can be installed on any REI3 instance as it is a REI3 application as well.
  • Manual import of applications: All applications can be imported manually. This is useful for development releases, testing and for applications not released in any repository.

Organizations starting with REI3 should rely on the official repository, switching to local ones when they scale up or self-developed applications become more prevelant.

Backup and recovery

To fully recover a REI3 instance, these components must be backed up:

  • The REI3 database
  • The REI3 configuration file config.json
  • The 'uploaded files' directory
  • The used SSL certificates

When running stand-alone, the integrated backup addresses all of the above and allows for full recovery as long as the target backup directory is separate from the application server. If not running in stand-alone or more control is required, more details are given below.

Files

The configuration file config.json is located in the chosen application directory for REI3. Certificates and file paths are referenced within the configuration file itself. For full recovery, copies of these are required.

Other directories besides the stated ones, do not need to be backed up but are not very large and can be included to keep backup jobs simple.

The configuration file can be reconstructed if lost and certificates newly created. This though would require effort and impede a quick recovery.

Database

In any deployment model, a PostgreSQL database is used for REI3. To access the stand-alone, integrated database, use the connection details from the REI3 configuration file (config.json) while the REI3 service is running. The database is called 'app' by default.

For full backups, we recommend using internal PostgreSQL tools, like pg_dump to backup and pg_restore to recover the database. Examples:

  • To backup to a directory: pg_dump -h HOSTNAME -p 5432 -U USERNAME -Fd -f TARGETDIR
  • To recover from a directory: pg_restore -h HOSTNAME -p 5432 -U USERNAME -d TARGETDBNAME SOURCEDIR

Good practices:

  • Always backup to a separate network location, in case the system fails completely.
  • Recoveries of full backups should always run against an empty / new database to make sure that all data can safely be recovered to the backed up state. The recovered database can then be renamed or the REI3 configuration file updated to access the recovered database.

Incremental backups are useful for larger instances but are not covered by this documentation. Organizations large enough to require these, should either use their existing backup solutions or follow documented PostgreSQL practices for executing incremental backups.

Updates

There are 2 kinds of updates to be handled - application updates and platform updates. Application updates are more common and serve to expand functionality for REI3 applications. These updates can be installed directly from the admin user interface, when the maintenance mode is active. If the updates are received via repository, its a single-click operation. Manual updates must be provided via packaged application files. It is good practice to install updates in testing environments first as looks and behaviour can change between application releases.

Platform updates address the underlying platform software and might be necessary for application updates as well, if these require newer platform features. Because security and stability issues are fixed with platform updates, it is always good to update the platform itself.

Platform updates

If the graphical installer for Windows is used, an update can be directly started by executing a later version of the installer. The platform service will automatically be restarted.

For Linux servers, stopping the service and overwriting files in the chosen application directory with the latest extractable package is required. Afterwards the service can be restarted.

To update the portable version, stop any running REI3 instance and extract the contents of a later portable version into the portable application directory.

Clustering and system performance

REI3 servers can be clustered to enable more requests and users to be handled at the same time. Before considering clustering, it is important to learn where perceived performance issues are coming from. REI3 is built to handle many users concurrently and is also able to use multiple processor cores and more memory to improve performance. Only if the CPU load/memory usage of the REI3 service is often very high, clustering multiple REI3 servers can make sense.

In most cases, performance issues come from other sources:

  • High database load. When running larger REI3 instances, the amount of requests can be too much for the database system. This can be seen by connecting to the database server and looking at its statistics. In this scenario, the REI3 service will be idle, while the database is overworked. To improve performance, the database system would need to be upgraded - either with better hardware or with clustering of the database system itself. Note that REI3 only supports clustered databases with the dedicated deployment model. Clustering REI3 itself would not improve performance in this case.
  • Missing or badly used indexes on database relations. This can be seen when connecting to the database server and running benchmarks on problematic requests. If indexes are not optimized, the author of the affected application can easily improve performance by updating them. Clustering REI3 would not result in any performance improvement in this case.
  • Slow storage. Either the database system or REI3 itself is accessing slow storage systems. This can be seen, when both the REI3 application service and database system have very little load but requests still take a long time. In this case, improving latency/throughput of the underlying storage system will have the most impact on performance. Clustering REI3 servers would not help.

Is the REI3 service actually the bottleneck, clustering can help - for this, the following requirements must be met:

  • REI3 must be running in dedicated deployment mode, meaning the database system must be separate from REI3 itself. Switching from stand-alone deployment to dedicated is always possible.
  • REI3 servers must access the same storage location for their file paths.
  • REI3 servers must access the same database.
  • It does NOT matter, whether REI3 servers are running on different operating systems or processor architectures.

Setting up clustering itself is very simple:

  1. The already running REI3 server is by default already part of a one-server cluster, with itself as the cluster master. Nothing needs to be done here.
  2. To add additional server nodes, install REI3 on other servers and use the same database and file path settings in the REI3 configuration file config.json.
    • The file paths for the entire cluster must point to the same storage location - usually networks shares work well for this requirement.
    • Choose any configuration in the 'web' part of the configuration file that fits with your infrastructure (which port to use, how certificate files are named, etc.).
    • The cluster/nodeId must be left empty for new server nodes.
  3. As soon as a new server node connects to the existing REI3 database, it will register itself as a new cluster node and assigns itself a unique node ID.

This is the entire setup. The cluster auto-configures and also automatically assigns cluster master role and tasks depending on which nodes are checking in.

Cloud operations

REI3 can be made accessible on the internet by opening up corresponding firewall ports. We, the REI3 manufacturers, aim to make the platform as secure as possible. As with any other application, it is always possible that undiscovered security flaws are exploited and unauthorized access achieved. Besides regularly updating REI3 itself, it is our view that additional safety measures are necessary to safely run web applications in the cloud, such as:

  • Running intrusion detection and prevention on the application server or firewalls
  • Applying hardening principles to cloud application servers
  • Using a DMZ to separate cloud accessible services from any local, protected networks

The REI3 platform does include bruteforce protection; as these are only a small subset of possible attacks, they cannot be relied upon alone for safe, cloud-connected operation. Additional actions (as described above) should be taken in all cases.