Skip to content

Installation, Services and Updates

Overview

This guide explains how to install the InfoConnect Hub distribution on a Windows, Linux or macOS host, run it from a console or as an operating system service, update it and check that it is running. It is intended for administrators who install and maintain the Hub.

The distribution archive contains all Hub modules and the start scripts that configure and launch them. For Docker, Kubernetes and Cloud Run deployments, see Deploying InfoConnect Hub with Docker, Kubernetes and Cloud Run.

Before you install, check the system requirements for the size of the host.


Distribution archive

The distribution is delivered as a ZIP archive named infoconnect-hub-<version>-distro.zip. Extract it into the intended product home directory. The archive has a single root folder, infoConnect-hub.

Folder Contents
info-connect-hub/ Hub module
info-connect-rpa-hub/ RPA Hub module (screen automation)
info-connect-mcp/ MCP server module
info-connect-ui/ Web UI module
info-connect-auth-server/ Optional authorization server for OAuth
start-scripts/ Launchers, setup wizards, service installers, update script and deployment assets
log/ Log files, created at run time

Every module folder follows the same pattern: info-connect-*/executable-jars/ holds the executable JAR and info-connect-*/config/ holds the module configuration (for example application.properties). Not every module is included in every archive; a module without a JAR is skipped at start.

The Hub stores its metadata in an embedded H2 database by default (info-connect-hub/config-db). Hub settings, including the database location, are in info-connect-hub/config/application.properties.

To run several Hub instances against one shared external metadata database (MySQL or IBM i), set db.sync.enabled=true in info-connect-hub/config/application.properties of every instance. Each instance then checks the database for changes to Connections, APIs and Data Flows about every 60 seconds. The property is false in the distribution archive, because instances cannot share an embedded H2 database.


Prerequisites

Requirement Details
Java 17.0.1 or newer, available on the PATH (java -version)
Windows PowerShell 5.1 or newer, or PowerShell Core (pwsh)
Linux / macOS bash. PowerShell and Python are not required
Linux systemd installation sudo privileges
Windows service installation An Administrator command prompt

Note

On operating systems other than Linux and macOS, infoconnect-hub.sh starts the Hub through PowerShell Core (pwsh).

Install folder path

Install the distribution into a folder whose path contains only letters, digits, - and _, for example C:\infoconnect-hub on Windows or /opt/infoConnect-hub on Linux.

On Windows, the launcher (infoconnect-hub.bat) and the service installer (service-setup.bat) print a warning when the install path contains spaces, special characters or non-Latin characters:

WARNING: the install folder path may cause startup problems:

The warning does not stop the start, but startup can fail from such a folder, for example with the error Unable to access jarfile. If it does, move the distribution to a path that contains only letters, digits, - and _, and start it again.


Ports

Module Port Notes
Hub 8080 Admin and Functional APIs
Auth server 8081 Optional, disabled by default
RPA Hub 8082 Screen automation
MCP server 8083 AI agent access
UI 8085 Web interface

The web interface calls its own backend under /api/infoconnect/... on port 8085 and forwards the requests to the Hub, for example /api/infoconnect/application/encryption/1 for encryption, where the number identifies the Hub that the UI is connected to. These paths are internal to the UI. Use the Admin API on port 8080 in your own clients, for example POST /admin/encryption.

When the modules are running, open the web interface at http://localhost:8085 and sign in with the UI credentials you entered during the first-run setup. Admin API and Functional API clients (Postman, cURL or any other REST client) use port 8080.

The UI calls the Hub on localhost:8080 after you sign in. If the Hub is disabled or not running, the UI login returns 401 Unauthorized.

Changing the ports

The ports above are defaults. If another application on your machine already uses one of them, change it. Each module reads its own port from the server.port property in its config/application.properties file, and the start scripts do not fix any port.

The modules also call each other by host and port. When you change the port of a module, change the matching properties in the other modules too, then restart all modules.

Module (default port) Where its port is set Change these properties to the same port
Hub (8080) server.port in info-connect-hub/config/application.properties infoconnect.hub.port in the UI module; hub.url in the MCP module
RPA Hub (8082) server.port in info-connect-rpa-hub/config/application.properties rpa.port in the Hub module; rpa.hub.port in the UI module; rpa.url in the MCP module
MCP server (8083) server.port in info-connect-mcp/config/application.properties infoconnect.mcp.port in the UI module; mcp.explorer.base-url in the MCP module
Auth server (8081) server.port in info-connect-auth-server/config/application.properties spring.oauth.resource.server.issuer-uri_BUILT_IN in the Hub, RPA Hub and MCP modules, if you use the built-in authorization server
UI (8085) server.port in info-connect-ui/config/application.properties None. Open the web interface at the new port.

The host properties next to these ports (infoconnect.hub.host, rpa.host, rpa.hub.host, infoconnect.mcp.host) are localhost by default. Change them only if the modules run on different machines.

For example, to run the Hub on port 9080:

  1. Set server.port=9080 in info-connect-hub/config/application.properties.
  2. Set infoconnect.hub.port=9080 in info-connect-ui/config/application.properties.
  3. Set hub.url=http://localhost:9080 in info-connect-mcp/config/application.properties.
  4. Restart the modules, as described in Running in a console.

Use the new ports in the health check as well. With Docker, the configuration wizard asks for the published Hub port, see Deploying InfoConnect Hub with Docker, Kubernetes and Cloud Run.


Running in a console

Run the launcher from the distribution root (the parent folder of start-scripts):

OS Command
Windows start-scripts\infoconnect-hub.bat
Linux / macOS start-scripts/infoconnect-hub.sh

Press Ctrl+C to stop the processes started by this session.

First run

If the configuration files are missing, the launcher runs two interactive wizards. The order is always credentials first, then modules.

Step Wizard Creates Content
1 Credentials (change-default-creds) start-scripts/config/.env User names, passwords, encryption word and optional API key
2 Modules (configure-modules) start-scripts/config/modules.conf Modules to start

The credentials wizard has no built-in default values: enter the values you want to use. The wizard copies the Hub user and administrator credentials into the RPA Hub entries.

The modules wizard accepts y or n in any case (yes and no also work). Press Enter to accept the value shown in brackets.

Module Default Notes
Hub Yes Core module, cannot be disabled
RPA Hub Yes
MCP Yes
UI Yes
Auth No Optional OAuth server, enable only if you need it

The .env file

start-scripts/config/.env holds credentials and secrets. A template is available as start-scripts/config/.env.example.

Key Purpose
UI_USERNAME, UI_PASSWORD UI login
HUB_USER_USERNAME, HUB_USER_PASSWORD Hub Functional API user
HUB_ADMIN_USERNAME, HUB_ADMIN_PASSWORD Hub Admin API user. The UI uses these credentials to call the Hub, so the Hub must run with the same pair
RPA_USER_USERNAME, RPA_USER_PASSWORD RPA Hub user
RPA_ADMIN_USERNAME, RPA_ADMIN_PASSWORD RPA Hub administrator
ENCRYPTION_WORD Encryption key. Passed to every Java module as -Djasypt.encryptor.password
AZURE_OPENAI_API_KEY Optional, used by the UI for LLM features

The UI login form checks UI_USERNAME and UI_PASSWORD, not the Hub administrator pair.

Warning

Running processes do not re-read .env. After any change to .env, restart all running modules. Values encrypted with one encryption word cannot be decrypted with another.

The modules.conf file

start-scripts/config/modules.conf selects the modules to start, one flag per module. A template is available as start-scripts/config/modules.conf.example.

hub=true
rpa=true
mcp=true
ui=true
auth=false
Rule Details
Accepted values true / false. The values yes / no, y / n and 1 / 0 are also accepted, in any case
hub Must be true. The console launcher stops with an error on false; the services start the Hub anyway with a warning
Enabled module without a JAR The module is skipped with a warning, the other enabled modules still start
Nothing to start The launcher reports No modules started

To run a narrower set of modules, for example the Hub only, edit modules.conf and start the launcher again in a new console session.

What a start does

  1. Loads modules.conf to determine the enabled modules.
  2. Stops any leftover InfoConnect Java processes from a previous run (all known modules, not only the enabled ones).
  3. Checks Java, creates the log files, loads .env and applies the JVM options.
  4. Starts each enabled module that has a JAR in its executable-jars folder.
  5. Prints a table of the running services and waits.
  6. On Ctrl+C, stops only the processes started by this session.

Log files

Log files are written to the log folder in the distribution root. There are two sets of files:

  • The start scripts redirect the console output of each module to infoConnect<Module>.out.log and infoConnect<Module>.err.log.
  • The Hub, the RPA Hub and the UI also write their own rolling log files, info_connect_hub, info_connect_rpa_hub and info_connect_ui with the suffix .out.log or .err.log. Each file rolls over at 10 MB and 10 files are kept. They contain mostly the same entries as the console files, so you can read either set. The MCP server and the Auth server have only the console files.
Module Output log Error log
Hub log/infoConnectHub.out.log log/infoConnectHub.err.log
RPA Hub log/infoConnectRpaHub.out.log log/infoConnectRpaHub.err.log
MCP log/infoConnectMCP.out.log log/infoConnectMCP.err.log
UI log/infoConnectUI.out.log log/infoConnectUI.err.log
Auth log/infoConnectAuth.out.log log/infoConnectAuth.err.log

Log levels

Each module reads its log levels from application.properties in its config folder, for example info-connect-hub/config/application.properties. The other folders are info-connect-rpa-hub, info-connect-mcp, info-connect-ui and info-connect-auth-server. The modules ship with INFO, which is the recommended level for production.

Property Default What it controls
logging.level.root INFO Everything without a more specific level
logging.level.com.infoviewsystems.as400 INFO InfoConnect components: APIs, data flows, MCP tools (Hub, RPA Hub, MCP server)
logging.level.com.infoview.as400 INFO IBM i connection pool, data queue reads and writes, program calls (Hub)
logging.http.request, logging.http.response OFF Request and response bodies of API calls (Hub, RPA Hub)

Log only warnings and errors. Set the InfoConnect levels to WARN:

logging.level.com.infoviewsystems.as400=WARN
logging.level.com.infoview.as400=WARN

At WARN the logs still show when the IBM i connection is lost, but not when it is restored, so keep at least WARN in production. The error log (*.err.log) contains only ERROR entries at any level.

Troubleshooting. Set the level to DEBUG only while you investigate, then set it back. At DEBUG the Hub logs every data queue read and connection pool operation, which can add hundreds of thousands of lines per day for a data flow with ten threads. To log request and response bodies, also set logging.http.request=DEBUG and logging.http.response=DEBUG. Passwords, tokens and keys are masked, but bodies can contain business data, so keep them OFF in production.

Restart the module after changing a level. In Docker or Kubernetes, set the same properties as environment variables instead, for example LOGGING_LEVEL_COM_INFOVIEWSYSTEMS_AS400=WARN.


Changing credentials or modules later

Re-run a wizard, or edit the files in a text editor and restart.

Task Script
Change credentials change-default-creds.bat / change-default-creds.sh
Select modules again configure-modules.bat / configure-modules.sh

Both scripts are located in start-scripts. Restart the modules after saving. If you run InfoConnect as a service, also see the service sections below.


Running as a Windows service

The installer registers a Windows service for each module that is set to true in modules.conf and has a JAR in the distribution. It uses WinSW (Windows Service Wrapper).

  1. Make sure start-scripts\config\.env and modules.conf exist. If they do not, the installer runs the same wizards as the console launcher.
  2. Open an Administrator command prompt and run the installer:

    start-scripts\service-setup.bat
    
Service ID Display name
InfoConnectHub InfoConnect Hub
InfoConnectRPAHub InfoConnect RPA Hub
InfoConnectMCP InfoConnect MCP
InfoConnectUI InfoConnect UI
InfoConnectAuth InfoConnect Auth server

The services start automatically with Windows and restart 60 seconds after a failure.

Warning

Installed services do not pick up changes in modules.conf. Run service-uninstall.bat and then service-setup.bat again as Administrator.

To remove the services, run service-uninstall.bat. It removes all five service wrappers, including those of modules that are disabled in modules.conf.

start-scripts\service-uninstall.bat

Running as a Linux systemd service

By default, the systemd installer uses the folder that contains start-scripts as the install root. Installing under /opt, for example /opt/infoConnect-hub, is recommended. The services run as the infoconnect user, which the installer creates if it does not exist. You can also pass a different absolute install root to install-systemd.sh.

Before the services start, start-scripts/config/.env must exist. If modules.conf is missing, the installer writes the defaults (all modules except Auth). If you run the installer from an interactive SSH session, it starts the same wizards as infoconnect-hub.sh for any missing file. Without a terminal (for example in automation), copy .env.example to .env and edit it before installing. To skip the wizards, run sudo SKIP_WIZARDS=1 bash install-systemd.sh.

Install

Change to the start-scripts folder and run the installer:

cd /opt/infoConnect-hub/start-scripts
sudo bash install-systemd.sh

Note

Run the installer as sudo bash install-systemd.sh. The command sudo install-systemd.sh does not work because sudo does not search the current directory.

The installer sets ownership of the installation tree to infoconnect, expands the unit templates, copies all unit files to /etc/systemd/system/, generates infoconnect.target with only the modules enabled in modules.conf and runs systemctl daemon-reload.

Module systemd unit
Hub infoconnect-hub.service
RPA Hub infoconnect-rpa.service
MCP infoconnect-mcp.service
UI infoconnect-ui.service
Auth infoconnect-auth.service

Start and enable

Start all installed modules and enable them at boot:

sudo systemctl enable --now infoconnect.target

To start a single unit instead:

sudo systemctl enable --now infoconnect-hub.service

A module without a matching JAR exits successfully and is not restarted.

Logs

Service output is available through the journal:

journalctl -u infoconnect-hub.service -f

Use the unit name of the module you need. Use -e instead of -f to show the most recent entries without following the log.

Java location

To set JAVA_HOME or PATH for a service, open the unit override and add an Environment= line under [Service]:

sudo systemctl edit infoconnect-hub

Changing modules or moving the installation

After you edit modules.conf or move the distribution, run sudo bash install-systemd.sh again, then sudo systemctl daemon-reload, and restart the units.

Line endings

Shell scripts must use LF line endings. If a script fails with bash\r: No such file or directory after you copy the distribution from Windows, remove the carriage returns:

find /opt/infoConnect-hub/start-scripts \( -name '*.sh' -o -name '*.service' -o -name '*.target' -o -name '*.ini' -o -name '*.example' \) -exec sed -i 's/\r$//' {} \;

Uninstall

The uninstall script stops and disables the units and deletes them from /etc/systemd/system/. It does not remove the installation folder or the infoconnect user.

sudo bash /opt/infoConnect-hub/start-scripts/uninstall-systemd.sh

Starting a single module

The start-scripts/solo-start/<module>/ folders contain launchers that start one module, for example start-hub-only.ps1 and start-hub-only.sh in solo-start/hub. The launchers honor modules.conf: a module that is set to false exits without starting. The Windows services and the systemd units use the same launchers.


Updating the installation

The update-from-distro script updates a native installation (console, Windows service or systemd) from a newer distribution archive. It replaces the info-connect-*/executable-jars/ folders, keeps your config/ folders and restarts the services. It does not update Docker or Kubernetes deployments.

Warning

The update keeps your config/ folders, so new properties from a newer distribution are not merged into your application.properties files. The application uses its built-in default for a missing property. Add the property manually if you need a different value.

Update from a URL

Provide the URL of the distribution archive. If the archive is hosted in cloud storage, include the shared access signature (SAS) query string.

OS Command
Windows (PowerShell) .\update-from-distro.ps1 -Url 'https://<host>/<path>/distro.zip?<sas-query>'
Windows (cmd) update-from-distro.bat -Url "https://<host>/<path>/distro.zip?<sas-query>"
Linux / macOS start-scripts/update-from-distro.sh --url 'https://<host>/<path>/distro.zip?<sas-query>'

On Linux, an installation under /opt usually requires sudo:

sudo bash /opt/infoConnect-hub/start-scripts/update-from-distro.sh --url 'https://<host>/<path>/distro.zip?<sas-query>'

Note

A SAS URL contains & characters. In PowerShell, use update-from-distro.ps1 with the URL in single quotes. Calling update-from-distro.bat with -Url from PowerShell splits the URL at &. As a fallback, set the IC_DISTRO_URL environment variable to the URL and run update-from-distro.bat without -Url.

Update from a local archive

Use --file (Linux / macOS) or -File (Windows) with a local ZIP file or an unpacked distribution folder.

start-scripts/update-from-distro.sh --file /path/to/infoconnect-hub-distro.zip

Options

Linux / macOS Windows Description
--url URL -Url URL Download the distribution archive
--file PATH -File PATH Use a local archive or unpacked folder
--dry-run -DryRun Show the plan without making any changes
--include-scripts -IncludeScripts Also refresh start-scripts. config/.env and modules.conf are preserved
--no-restart -NoRestart Do not stop and start the services. Restart them yourself to load the new JARs
--keep-download -KeepDownload Keep the downloaded archive and the staging folder
--install-root PATH -InstallRoot PATH Installation root. Default: the parent of start-scripts
--list-backups -ListBackups List the available backups
--rollback [BACKUP_DIR] -Rollback [BACKUP_DIR] Restore a backup. Default: the latest one

Backups and rollback

Each update first backs up the current JARs to <install-root>/backup/update-<timestamp>/. To list the available backups:

start-scripts/update-from-distro.sh --list-backups

To roll back to the latest backup:

start-scripts/update-from-distro.sh --rollback

To roll back to a specific backup, pass its folder:

start-scripts/update-from-distro.sh --rollback /opt/infoConnect-hub/backup/update-<timestamp>

On Windows:

start-scripts\update-from-distro.bat -ListBackups
start-scripts\update-from-distro.bat -Rollback

Health check

The Hub provides a health endpoint on its API port. The endpoint does not require authentication.

curl http://localhost:8080/actuator/health

A running Hub answers with HTTP status 200 and a JSON body whose status field is UP. The Hub health check only reports that the Hub process is up. It does not check the metadata database or the connection to IBM i.

The MCP server also provides /actuator/health on its port (http://localhost:8083/actuator/health). To check the RPA Hub, call an RPA Hub API such as GET /admin/connections on port 8082 with the RPA administrator credentials.


Troubleshooting

Symptom What to check
The wizard does not appear under systemd The wizards run during sudo bash install-systemd.sh from an interactive SSH session when the files are missing. systemctl start alone has no terminal. Without SSH, create .env and modules.conf manually from the .example files
Please answer y or n repeats without waiting Update the start scripts and run the wizard again, or copy modules.conf.example to modules.conf
Enable ?, hub]=true or RPA} appears in paths The *.ini files have CRLF line endings. Strip them with sed -i 's/\r$//' start-scripts/config/*.ini, delete modules.conf and run the wizard again
No modules started All enabled modules are missing their JARs, or every module is set to false in modules.conf
Port already in use A leftover Java process from a previous run is using the port. Run infoconnect-hub again (it stops leftover processes at start) or stop the processes manually
modules.conf or .env missing on Linux Run change-default-creds.sh and configure-modules.sh
UI login fails after editing .env Restart all running modules. Sign in with UI_USERNAME and UI_PASSWORD. Make sure hub=true in modules.conf and the Hub is running on port 8080
Login works on Windows but returns 401 on Linux The UI configuration in info-connect-ui/config/application.properties may contain a fixed uiUser value instead of the .env placeholders. Read the WARNING printed by the launcher at start, correct the configuration and restart
bash\r: No such file or directory The scripts have CRLF line endings. See Line endings
Unable to access jarfile on Windows The install folder path contains spaces or special characters. See Install folder path
systemd service fails immediately Check journalctl -u infoconnect-hub -e, the .env and modules.conf files, and that the infoconnect user can read the installation folder
systemd reports "Not a script file" although the path is correct The infoconnect user cannot read the folder, which is common under a home directory with restricted permissions. Move the installation under /opt and re-run install-systemd.sh