AdminDocu-en_us

Updated 2021-09-14

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. Builder option
    2. SSL certificates
  7. General administration
    1. Maintenance mode
    2. Authentication and authorization
    3. Connecting logins to data sets
    4. Authentication and authorization via LDAP
  8. Manage applications
  9. Backup and recovery
    1. Files
    2. Database
  10. Updates
    1. Platform updates
  11. Hosting your own REI3 instance in the cloud

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.

REI3 itself is an application service that serves pre-build web applications. REI3 applications build upon each other to reuse data and expand functionality.

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 limited to 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 UI. 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 when the situation changes.

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 to 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
    • Linux server (REI3 is tested on Debian, CentOS and Ubuntu Server)
    • Windows Server 2016 or later
  • Memory
    • For medium size installations (~250 users), 4+ GB should be available to the application.
  • Disk space
    • REI3 itself uses less than 500 MB of disk space.
    • Besides the application, disk space is required for the database (if stand-alone) and file uploads. To be safe, a conservative estimation would start with 50 GB.
  • Software
    • On Windows Server: Microsoft Visual C++ 2015
  • Databases (dedicated deployment only)
    • A PostgresSQL 12.2 or newer database with full permissions

Clients

To access a running REI3 instance, any modern browser can be used. 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 with installed desktop experience. The installer supports both stand-alone and dedicated deployment models.

When choosing the stand-alone deployment model, following this installer is sufficient for the basic installation and REI3 can be started immediately.

When choosing the dedicated model, database connection details for a running, empty PostgreSQL database must be entered into the configuration file config.json, inside the chosen application directory. With valid connection details to its database, REI3 will automatically complete the setup process on its first start.

Independent of deployment model, on Windows Server, REI3 is handled as a Windows service and can be started as such. Should the service not start, REI3 will write to the Windows application log.

On a Linux server

For Linux servers REI3 currently provides a compressed archive with pre-compiled binaries. After extraction at a location of your choice, the file r3 must be made executable and the configuration file config.json copied from its template file config_template.json.

Before running REI3, you must enter valid connection details to a running, empty PostgreSQL database inside config.json. With valid connection details to its database, REI3 will automatically complete the setup process on its first start.

To register REI3 as a service with your operating system, execute r3 -install with elevated permissions. REI3 writes to syslog, which can be referenced should the service not start.

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 UI 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.

Builder option

The REI3 platform primarely hosts pre-build applications for users to access. It also contains a graphical application builder. This component can be enabled by switching the builder option to true inside the configuration file. Once REI3 has restarted, admin users can access the builder by switching to mainenance mode inside the admin UI.

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 in all cases. The portable version makes this easy on Windows clients. On Linux a separated application service, accessing a separate database, serves the same purpose.

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 include certification services.

General administration

After configuration, basically all administrative tasks are executed via the admin UI 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.

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 login names. 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 UI.

Connecting logins to data sets

Some applications relate data sets to logged in users to facilitate workflows. One example is the official core 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 UI. 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.

If required, we also offer support services for organizations for setting up sensible backup solutions and for recovery scenarios.

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 UI, 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.

Hosting your own REI3 instance in the cloud

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.