Installation

Get OIBus installed and running in under 2 minutes.

System Requirements

Before installing OIBus, ensure your environment meets these minimum requirements:

Resource	Minimum Requirement	Notes
RAM	2 GB	Actual usage depends on your configuration and data volume.
Disk Space	200 MB	Additional space (several GB) recommended for data buffering and caching.
Administrative Rights	Required	Needed to install OIBus and register it as a service.
Web Browser	Modern browser (Chrome, Firefox, Edge)	Internet Explorer is not supported.

Supported Operating Systems

OIBus is officially supported on the following platforms:

Operating System	Version(s)	Notes
Windows	10, 11, Server 2016/2019/2022/2025	64-bit versions only.
Linux	Ubuntu 20.04 and later, Debian 10/11, RHEL 8/9	x64 and ARM64 architectures.
macOS	11 (Big Sur) and later	Apple Silicon (M1/M2) and Intel supported.

caution

• You need a modern web browser to access the OIBus configuration interface.
• The browser can be on the same machine or remote, but you must configure access settings.

Installation steps

Select your operating system for step-by-step instructions:

Windows

Choose the installation method that best fits your needs:

• Use the Installer for a guided, user-friendly setup.
• Use the Scripts method for advanced users or to install multiple OIBus services.

Installer

Download

OIBus v3.7.4 (x64 installer)

Windows (x64)

Installation Steps

1. Run the Installer Launch the downloaded installer. You will see the welcome screen:

2. Accept the License Read and accept the EU-PL license to proceed.

3. Choose Installation Path Select the directory where OIBus binaries will be installed:

4. Set Data Directory Choose where to store cache, logs, and configuration files:

tip

For data safety, consider placing the data folder on a separate disk (e.g., D:\OIBusData). This helps prevent disk space issues on the system drive and improves reliability.

5. Confirm and Install Review your settings and confirm to begin the installation:

6. Complete Installation Once the installation is complete, you'll see a confirmation screen. Proceed to the first access guide to configure OIBus.

Update OIBus

• Use the OIBus Windows Installer to update.
• Specify the current executable and configuration paths.
• Choose to keep or replace your existing configuration.
• The OIBus service will briefly stop during the update.
• On first startup after the update, the oibus.db configuration database will be automatically upgraded.

Uninstall OIBus

1. Navigate to the OIBus binary folder.
2. Run unin000.exe as an administrator:

3. Follow the prompts to remove OIBus:

Scripts

Download

OIBus v3.7.4 (zip)

Windows (x64)

Installation Steps

1. Extract the Zip Archive

Unzip the downloaded file into the directory where you want to install OIBus (e.g., C:\Program Files\OIBus).

2. Run the Installation Script Open an administrator terminal in the extracted folder and run:

Usage

install.bat -c "[your-data-folder-path]"

Replace [your-data-folder-path] with the actual path where you want to store OIBus data (e.g., C:\OIBusData or D:\OIBusData).

tip

• If you omit the -c argument, the script will prompt you for the data path.
• For data safety, consider placing the data folder on a separate disk (e.g., D:\OIBusData). This helps prevent disk space issues on the system drive and improves reliability.

Example:

Example with terminal outputs

install.bat -c "D:\OIBusData"
> Administrator permissions required. Detecting permission...
> Stopping OIBus service...
> Installing OIBus as Windows service...
> The "OIBus" service has been successfully installed!
> Configuration of the "AppDirectory" parameter value for the "OIBus" service.
> nssm set OIBus AppNoConsole 1
> Starting OIBus service...
> OIBus: START: Operation successful.
> Creating go.bat
> echo Stopping OIBus service... You can restart it from the Windows Service Manager
> nssm.exe stop OIBus
> "C:\Users\Administrator\Downloads\oibus-win_x64\oibus.exe" --config "D:\OIBusData"

tip

Use -n "Service Name" to customize the OIBus service name. This method is useful if you need to run multiple OIBus services on the same machine.

By default, the service name is OIBus.

Proceed to the first access guide to configure OIBus.

Update OIBus

1. Extract the new files from the zip archive.
2. Open the Windows Service Manager and stop the OIBus service.
3. Replace the old files in the OIBus executable directory with the new ones.
4. Restart the OIBus service.
5. On first startup, the oibus.db configuration database will be automatically upgraded.

Uninstall OIBus

Run the following command in an administrator terminal:

Example with terminal outputs

uninstall.bat -n "OIBus"
> Administrator permissions required. Detecting permission...
> Stopping OIBus service...
> Removing OIBus service...

caution

The data folder is not automatically removed. Delete it manually if needed.

Linux

Download

OIBus v3.7.4

Linux (x64)

OIBus v3.7.4 (zip)

Linux (ARM 64)

Alternatively, download and extract the files using these commands:

curl -LO https://github.com/OptimistikSAS/OIBus/releases/download/v3.7.4/oibus-linux_arm64-v3.7.4.zip
unzip -a oibus-linux_arm64-v3.7.4.zip -d OIBus/

Extracted Files

The archive contains:

• oibus-launcher – Launcher for the OIBus binary
• binaries/oibus – OIBus executable
• oibus-setup.sh – Installation script
• oibus-uninstall.sh – Uninstallation script (updated during installation)

note

The provided bash scripts have been tested on Ubuntu and are designed to set up OIBus as a system service. For other distributions, you may need to adapt the script.

Install OIBus as a Linux Service

1. Unzip the downloaded file into the directory where you want to install OIBus.

2. Run the installation script with administrative privileges:

sudo ./oibus-setup.sh

3. Follow the interactive prompts (default values shown in parentheses):

Administrative permissions are required to proceed. Do you wish to continue? (Y/n)
Enter the directory for OIBus binaries (default: ./OIBus/):
Enter the directory for OIBus data, caches, and logs (default: ./OIBusData/):
Enter a username for your OIBus session (default: admin):
Enter a name for your OIBus instance (default: OIBus):
Enter the port for OIBus (default: 2223):

4. After successful installation, you'll see:

Service file successfully created. Enabling oibus service startup on system boot...
Created symlink /etc/systemd/system/default.target.wants/oibus.service → /etc/systemd/system/oibus.service.
Starting OIBus service...
Installation procedure completed!

5. Access OIBus at http://localhost:2223/

6. Useful commands:

# Check service status
sudo systemctl status oibus

# View service logs
sudo journalctl -u oibus -f

Get familiar with the OIBus interface on the first access page.

Update OIBus

1. Download the latest version and extract it.
2. Stop the OIBus service.
3. Replace the binary files where it has originally been installed.
4. Restart the OIBus service.

Uninstall OIBus

1. Navigate to the OIBus binary directory and run:

sudo ./oibus-uninstall.sh

2. Choose whether to remove all data when prompted

caution

Selecting to remove all data will permanently delete your configuration, credentials, and logs.

Administrative permissions are required to proceed with uninstall. Do you wish to continue ? (Y/n)
Administrative permissions granted.
Do you wish to remove all OIBus data (cache, logs...)? All data, credentials and logs about your current OIBus will be permanently erased. (y/N) y
Removed /etc/systemd/system/default.target.wants/oibus.service.
OIBus service was successfully removed.

Run OIBus in Standalone Mode

To run OIBus without installing as a service:

./oibus-launcher --config ./OIBusData

tip

Ensure the OIBusData directory exists before running this command.

macOS

Download

OIBus v3.7.4

MacOS (Intel chip)

OIBus v3.7.4

MacOS (ARM 64)

Run OIBus on macOS

1. Extract the downloaded archive to a location of your choice

2. Open Terminal and navigate to the folder containing the OIBus binary

3. Run OIBus with the following command:

./oibus-launcher --config [your-data-folder-path]

Replace [your-data-folder-path] with the path where you want to store OIBus configuration and cache files.

Example:

./oibus-launcher --config ~/oibus-data

Requirements

• You need admin permissions to run the binary
• The binary must be run from its own folder

Allow App Execution

On macOS, you may need to manually allow the execution of the OIBus binary:

1. When first running OIBus, you'll see a security warning
2. Go to System Settings > Privacy & Security
3. In the Security section, click Allow Anyway for:

• oibus-launcher
• oibus (which is run by the launcher)

note

You'll need to perform this operation twice - once for each binary.

Access OIBus

After successfully launching OIBus, access the interface at: http://localhost:2223/

Get familiar with the OIBus interface on the first access page.

Docker

Download

docker pull ghcr.io/optimistiksas/oibus:v3.7.4

Run the Container

docker run --name oibus-container \ -d \ -p 2223:2223 \ -v "./OIBusData:/app/OIBus/OIBusData" \ oibus

Persistent Data Volume

The volume mount (-v) is highly recommended to:

• Persist configuration between container restarts
• Access logs and cache files
• Maintain your configuration database
• Store historical data

Without a volume, all data will be lost when the container stops.

Container Configuration

Port Configuration

Port	Purpose	Configuration
2223	Web interface	Exposed by default (-p 2223:2223)
[custom]	Proxy server	Add -p [HOST_PORT]:[CONTAINER_PORT] to expose

Port Configuration Warning

Important: Never change the HTTP port (2223) from within the OIBus web interface when running in Docker. Changing this port will make the web interface inaccessible as the container only exposes port 2223 by default.

Proxy Server Setup

To use OIBus as a proxy server in Docker:

1. Configure the proxy port in OIBus settings (e.g., 9000)
2. Update your docker run command:

docker run --name oibus-container \ -d \ -p 2223:2223 \ -p 9000:9000 \ -v "./OIBusData:/app/OIBus/OIBusData" \ oibus

3. Ensure your firewall allows traffic on the proxy port

Best Practices

Volume Management

• Create a dedicated directory for OIBus data on your host
• Set appropriate permissions: chmod 775 OIBusData
• Consider using named volumes for production deployments

Resource Limits

docker run --name oibus-container \ -d \ --memory="2g" \ --cpus="2" \ -p 2223:2223 \ -v "./OIBusData:/app/OIBus/OIBusData" \ oibus

Docker Compose Example

version: '3.8'
services:
oibus:
  image: ghcr.io/optimistiksas/oibus:v3.7.4
  container_name: oibus-container
  ports:
    - '2223:2223'
  volumes:
    - ./OIBusData:/app/OIBus/OIBusData
  restart: unless-stopped
  environment:
    - TZ=UTC
  # Uncomment to set resource limits
  # deploy:
  #   resources:
  #     limits:
  #       cpus: '2'
  #       memory: 2G