Table of contents
- Deployment models
- Technical requirements
- First access to REI3
- General administration
- Manage applications
- Backup and recovery
- Clustering and system performance
- Cloud operations
This is the documentation for deploying and operating the REI3 application platform. It assumes some 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.
Depending on the environment, different deployment models are available.
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 and includes an integrated database. It is the recommended model for organizations with smaller IT teams.
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.
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.
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:
- Intel, AMD or ARM processors (x64 or ARM64), multiple cores provide better performance
- 4+ GB
- Disk space
- 500 MB for REI3 itself
- 20+ GB for the database and file uploads (scales with use)
- Linux server
- Optional: ImageMagick (for thumbnails)
- Optional: Ghostscript (for PDF thumbnails)
- Optional: PostgreSQL client tools (for integrated backups)
- Windows Server
- Required: Microsoft Visual C++ 2015 (or newer)
- Optional: Ghostscript (for PDF thumbnails)
- Linux server
- Databases (dedicated deployment only)
- PostgresSQL 13.0 database (or newer), UTF8 encoded, with full permissions
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
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, UTF8 encoded PostgreSQL database must be entered into the configuration file
config.json. The file
config.jsonis 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.
Because of licensing terms, we cannot distribute Ghostscript with REI3. If you want to create PDF thumbnails, you have to download and install a current version of Ghostscript on the REI3 server.
On a Linux server
For Linux servers, REI3 is available as a compressed archive with pre-compiled binaries. The installation steps are:
- Extract the REI3 archive file to a location of your choice (
- Make the file
chmod u+x r3).
- Copy the file
config.json- keep it in the same directory as the
- Add connection details to an empty, UTF8 encoded PostgreSQL database to
config.json. The database user must have full permissions for the chosen database.
- Optional: Install ImageMagick and Ghostscript if you want to have thumbnails (
sudo apt install imagemagick ghostscript).
- Optional: Install PostgreSQL client tools if you want to use the integrated backup feature (
sudo apt install postgresql-client).
- Register REI3 with your service manager (
sudo ./r3 -install).
- Start the REI3 service (
systemctl start rei3for example).
If the service does not start, REI3 writes to
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.
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.
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.
Some common considerations / pitfalls:
- REI3 can work with different certificates. If REI3 cannot load a certificate, it will fail to start and log to the operating system (
syslogfor Linux, Windows application log otherwise).
- Make sure that the hostname that the certificate is set to, is the same as clients use to connect to the REI3 server. The port is irrelevant.
- When running REI3 internally (not reachable from the cloud), clients still need to be able to verify the certificate. Make sure that your certificate file (*.crt) includes all certificates up the chain until the one that is known to the clients - this is usually a trusted root certificate or intermediary.
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.
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.
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
To let users access the system, individual logins must be created by an REI3 administrator or imported from a directory service. Login names can be anything from names to employee IDs to email addresses - they only need to be unique within a REI3 instance.
To access any application or data, roles have to be assigned to logins. This can be done by an REI3 administrator manually, or they can be assigned automatically according to group memberships within a directory service. Role permissions are cumulative - the more roles a user has, the larger the access.
To increase account security, REI3 administrators can choose password complexity options in the admin interface. Additionaly, MFA (multi-factor authentication) in the form of TOTP (time-based one-time-passwords) is available to users and can be reset by administrators. MFA can be setup on multiple devices and is supported by most authenticator apps (anything that supports TOTP).
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.
Connecting logins to data sets
To facilitate workflows and other features with relation to the current user, logins can be connected to data sets. One example is the application 'Organizations', which connects logins to company contacts. With this connection, applications can use organization details of the corresponding company contact to retrieve contact information, assign work, track time, manage projects and so on.
There is no limit in the number of applications or data sets that can be connected to a login. Logins can also be connected to other entities like customers, requestors and so on.
If at least one app that offers connecting data sets to logins is installed, REI3 administrators can create new or assign existing data sets in the admin interface for logins.
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 (
- Directories (can be renamed in
certificates(used SSL certificates)
The integrated backup feature automatically backs up all necessary data, if its enabled in the admin panel and dependencies are installed.
With larger systems, the integrated backup might not be good enough; it can only create full backups, which are very safe but take more time and disk space than other backup methods. With growing data sets, you might need to consider also using incremental/differential backups; these require more effort and possibly infrastructure and are not part of this documentation.
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
- 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.
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.
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:
- 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.
- To add additional server nodes, install REI3 on other servers and use the same database and file path settings in the REI3 configuration file
- 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.).
cluster/nodeIdmust be left empty for new server nodes.
- 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.
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.