1. Documentation
2. Installing & Connecting

2. Installing & Connecting

2.1 System Requirements

The standard RapidContext download package comes bundled with most of its dependencies. Additional launchers for Docker and Mac OS X are also available separately.

• Web Browser — All modern browsers work, with full support for:
  • Apple Safari 11+
  • Google Chrome 69+
  • Microsoft Edge 79+
  • Mozilla Firefox 65+
• Server Environment — Only needed on the RapidContext server (unless Docker is used).
  • Java Runtime (JRE) 11+
  • Unzip or similar utility
  • Bash shell or cmd.exe on Windows

2.2 Docker Images

The easiest way to run RapidContext is with a pre-built Docker image. This only requires a Docker server and supports standard port-mapping and local data volume arguments:

$> docker run \
     -p 8080:80
     -v local-data:/opt/local \
     ghcr.io/baraverkstad/rapidcontext:vXYZ
  

The command above starts a new server on localhost:8080 and creates a default admin user on the first run (unless other users are found).

The Docker image is based on Alpine Linux for minimal size. It is multi-architecture and supports both linux/amd64 and linux/arm64. The list of available versions shows the image tags available. Note that latest references the current development version.

An alternative way to run RapidContext in Docker is to build your own image. This can either be built from scratch, or reuse the default image to install additional software, etc:

FROM ghcr.io/baraverkstad/rapidcontext

# Install extras
RUN apk add --no-cache ...

# Diagnostics
HEALTHCHECK --timeout=5s CMD \
    wget -q --spider http://localhost/rapidcontext/status
  

Either way, the RapidContext Dockerfile is a good reference for how to build an image.

2.3 Server Installation

RapidContext can be installed either as a stand-alone server (recommended) or inside a Java Servlet container, such as Jetty or Tomcat. To install and start the stand-alone server, follow the steps below:

When run from the command-line, RapidContext supports different modes and provides a number of options:

$> bin/rapidcontext --help
Usage: [1] rapidcontext [--app] [<options>]
       [2] rapidcontext --server [<options>]
       [3] rapidcontext [--script] [<options>] [<procedure> [<arg1> ...]]

Alternative [1] is assumed when no procedure is specified.
Alternative [3] is assumed when a procedure is specified.

Options:
     --app             Launch in interactive application mode.
     --server          Launch in server mode.
     --script          Launch in script execution mode.
  -h,--help            Displays this help message,
  -l,--local <dir>     Use a specified local app directory.
  -p,--port <number>   Use a specified port number (non-script mode).
  -d,--delay <secs>    Add a delay after each command (script mode).
  -t,--trace           Print detailed execution trace (script mode).
  -u,--user <name>     Authenticate as a another user (script mode).
     --stdin           Read commands from stdin (script mode).
  -f,--file <file>     Read commands from a file (script mode).
  

To install RapidContext in a Java servlet container, use the file rapidcontext.war inside the ZIP distribution and follow the deployment instructions for your server.

The RapidContext server is also available as a convenient RapidContext.app launcher application for Mac OS X. Once started, it shows a simple server control panel as below:

2.4 Plug-in Installation

Plug-ins are installed or updated by using the built-in Admin app. The steps below explain how to install or update a plug-in:

1. Launch or go to the Admin app
2. Choose the Plug-Ins tab
3. Locate the Software Install & Update panel at the top (see screenshot)

   

4. Click the Browse... button and choose the plug-in file
5. Wait for the upload to complete
6. Click the Install / Update Plug-In button
7. The plug-in is now installed and activated

2.5 Plug-in Activation & Deactivation

Plug-ins can both be loaded and unloaded in the built-in Admin app. The steps below explain how to do it.

1. Launch or go to the Admin app
2. Choose the Plug-Ins tab
3. Locate the Plug-In List panel (see screenshot)

   

4. Select the plug-in to activate or deactivate
5. Press the corresponding Load or Unload button
6. The plug-in is now activated or deactivated

2.6 Plug-in Removal

Normally, it is not necessary to completely remove a plug-in from the server. Leaving it in unloaded status ensures that it has no effect on the system. Nevertheless, a plug-in can be completely removed by the following steps:

1. Launch or go to the Admin app
2. Choose the Plug-Ins tab
3. Ensure that the plug-in is currently not loaded
4. On the server — Go to the plugin/ directory
5. On the server — Remove the [plugin].zip file
6. Press the Restart button in the Admin app
7. Verify that the plug-in is no longer in the list of plug-ins

2.7 Connections

Connections to external systems can be created and modified in the built-in Admin app. The steps below explain how to do it:

1. Launch or go to the Admin app
2. Choose the Connections tab
3. Select the connection to modify (if appropriate, see screenshot)

   

4. Press the edit OR the "+" icon in the Connection Details view (to the right)
5. The connection editing dialog is shown (see screenshot)

   

6. Select the appropriate type and edit the details
7. Press Save to save and validate the connection

The connection will automatically be validated (tested) when modified or created in the Admin app. Any previously open communication channels will be closed and a single new one will be established. The results are visible in the Connection Details view.

A number of things should be noted regarding connections and connection editing:

• Advanced Settings — The advanced settings for a connection becomes visible when checking the Show all parameters checkbox in the edit dialog.
• Connection Channels — Each connection may open one or more connection channels (i.e. a TCP or UDP connection) to the external service. The number of currently open and used channels is shown in the Connection List view.
• Connection Pooling — Connection channels are often not closed immediately after use, but instead pooled for reuse (depending on connection type). This improves performance and reduces resource usage. The size of the pool can be controlled with the Max Open and Max Idle Secs parameters.
• Connection Types — Connections may behave somewhat differently depending on the connection type. Read the separate documentation for the relevant plug-in for more information.
• Transactions — Some connection types support transactions, in which case each call to the server will be encapsulated in a new transaction. The same transaction may span several connections.

2.8 Environments

An environment is used to signal the RapidContext server location to the user. The environment name is displayed at the top right corner of the standard user interface, along with the user name. Environments are primarily useful when several RapidContext servers are in use.

There is currently no user interface for editing or creating environments, so they must be manually added to the plugin/local/environment/ directory (or the environment/ directory in your plug-in). The file name should follow normal storage rules, i.e. [identifier].properties. See below for an example environment file.

# General properties
id = EXAMPLE
type = environment
description = The example environment
connections = EXAMPLE/
  

The connections property is used as a prefix when locating connections. I.e. all connection identifiers in the environment should be named [prefix]/[identifier], but only the identifier part should be specified on usage (in procedures and similar).

This will make it possible to add support for multiple environments with similar connections in a future version.