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:
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:
- Set
server.port=9080ininfo-connect-hub/config/application.properties. - Set
infoconnect.hub.port=9080ininfo-connect-ui/config/application.properties. - Set
hub.url=http://localhost:9080ininfo-connect-mcp/config/application.properties. - 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.
| 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
- Loads
modules.confto determine the enabled modules. - Stops any leftover InfoConnect Java processes from a previous run (all known modules, not only the enabled ones).
- Checks Java, creates the log files, loads
.envand applies the JVM options. - Starts each enabled module that has a JAR in its
executable-jarsfolder. - Prints a table of the running services and waits.
- 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.logandinfoConnect<Module>.err.log. - The Hub, the RPA Hub and the UI also write their own rolling log files,
info_connect_hub,info_connect_rpa_hubandinfo_connect_uiwith the suffix.out.logor.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:
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).
- Make sure
start-scripts\config\.envandmodules.confexist. If they do not, the installer runs the same wizards as the console launcher. -
Open an Administrator command prompt and run the installer:
| 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.
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:
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:
To start a single unit instead:
A module without a matching JAR exits successfully and is not restarted.
Logs
Service output is available through the journal:
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]:
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.
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.
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:
To roll back to the latest backup:
To roll back to a specific backup, pass its folder:
On Windows:
Health check
The Hub provides a health endpoint on its API port. The endpoint does not require authentication.
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 |