Installing Codabix

Codabix is available for the following operating systems and hardware configurations:

You can install Codabix on both workstation and server editions of Windows.
Codabix runs on both 32-bit and 64-bit versions of Windows, though we recommend to run the 64-bit version of Codabix for stability reasons.

System Requirements

Supported Operating Systems

Codabix for Windows is supported on the following operating systems:

Windows Version Workstation Operating System Server Operating System
6.1.7601 Windows 7 SP1 1) Windows Server 2008 R2 SP1 2) (Option “Full Installation”)
6.2.9200 Windows 8 (Windows Embedded 8 Standard) Windows Server 2012 (Option “Server with GUI”)
6.3.9600 Windows 8.1 Windows Server 2012 R2 (Option “Server with GUI”)
10.0.14393 Windows 10 [IoT] Enterprise 2016 LTSB Windows Server 2016 (Option “Server with Desktop Experience”)
10.0.16299 Windows 10 Version 1709 (Fall Creators Update)
10.0.17134 Windows 10 Version 1803 (April 2018 Update)
10.0.17763 Windows 10 [IoT] Enterprise 2019 LTSC Windows Server 2019 (Option “Server with Desktop Experience”, or “Server Core” with Server Core App Compatibility FOD installed)
Windows 10 Version 1809 (October 2018 Update) Windows Server, version 1809 (with Server Core App Compatibility FOD installed)
10.0.18363 Windows 10 Version 1909 (November 2019 Update) Windows Server, version 1909 (with Server Core App Compatibility FOD installed)
10.0.19041 Windows 10 Version 2004 (May 2020 Update) Windows Server, version 2004 (with Server Core App Compatibility FOD installed)
10.0.19042 Windows 10 Version 20H2 (October 2020 Update) Windows Server, version 20H2 (with Server Core App Compatibility FOD installed)

Hardware Requirements

Recommended: 64-bit Quad-Core CPU, 8 GB RAM

Back-end Database Requirements

By default, Codabix uses an embedded database (SQLite) which doesn't have any additional requirements.

However, if you plan on using MySQL, MariaDB, or Microsoft SQL Server as a back-end database, please make sure it is MySQL 8.0 or higher, MariaDB 10.3 or higher, or Microsoft SQL Server 2012 or higher.
We recommend running MySQL/MariaDB/MSSQL on the same machine as Codabix.

Codabix Setup and First Start

Codabix Setup

In order to install Codabix, download and run the Codabix installer (MSI file). You can select which Plugins are to be installed with Codabix.

Screenshot of Codabix Setup

Install and Uninstall Plugins

If you want to change your Codabix installation at a later time (e.g. to remove or add plugins), simply start the Codabix Installer again (alternatively, you can also open the Windows Control Panel, click on “Programs and Features”, select “Codabix” and click “Change”).
You can then click “Change” in the installer to change the Codabix plugins to be installed or uninstalled.

Updating Codabix

When you have already installed Codabix and want to update to a newer version, you don't need to uninstall the older version. Simply run the Codabix Installer of the newer version, and it will automatically update Codabix.
Note: If you had installed Codabix as a service, you will need to reinstall the service in the Codabix Settings dialog after the update.

First Start

You can start Codabix by double-clicking the Codabix shortcut Codabix on the Desktop, or by running the following command on the command line (e.g. on Windows Server Core):

The first time you start Codabix, you will be asked to specify a project directory (best would be an empty folder) where Codabix will be allowed to store its data (settings, database, configuration, logfiles etc).

After you confirm the selection, the Settings Dialog (see next section) will appear. Click OK to apply the settings. Then, a dialog box will ask you to set an admin password. You will need this password later for the configuration.

Note: A dialog of the Windows Firewall may appear asking to allow access to Codabix. This is caused by the OPC UA Server Plugin, which creates an OPC UA Server at port 4840 by default. If you click on “Allow access”, other machines in the network may access this OPC Server.

Screenshot of Windows Firewall Dialog

After you have set the passwort and Codabix has started, the Web Configuration login screen appears. You can now log in with the username admin and your previously set password.

Screenshot of Codabix Start Screen

Codabix Project Settings

Codabix provides a number of settings which you can configure for the selected project. To edit the settings, click on the gear toolbar item at the top right () which opens the Codabix settings dialog.

Basic Settings

Setting Name Description
Project Directory The project directory specifies the folder where Codabix stores the project settings (all of the following settings), the back-end database (if Back-end Database Mode is set to “Embedded (SQLite)”), log files and configuration files for the plugins. It can be retrieved using the environment variable %CodabixProjectDir%, e.g. in Scripts.
It contains the following folders:
log: Contains the Codabix runtime log files and log files from the Entity Model.
plugins: Contains configuration files for plugins.
webfiles: In this folder, you can place static files that should be accessible through the embedded Codabix web server for URLs starting with /webfiles/, if the setting Serve Static Web Files is enabled.
dashboard: Similar to webfiles, but for URLs starting with /dashboard/ in order to override the embedded Dashboard and use your own one.
userdata: You can place custom files in this folder (e.g. for use by Scripts). This folder is guaranteed to not be used differently in future Codabix versions.

When creating a backup, the contents of these subfolders will be included in the backup.
Project Name Allows you to specify a name for the current project, which will be displayed in the Codabix application's title bar and used for the default backup file name.
Access Security Within Codabix, the project logic can access files on your system by creating File Nodes (and then accessing them using the HTTP Access URL or using an OPC UA Client), or by creating a Script that uses the io.file and namespaces. To prevent a user that has the Codabix admin password (or is able to create Scripts or File Nodes in Codabix) from accessing arbitrary files on the system (especially when running as a service), you can allow or deny access to specific paths.
Furthermore, you can define alternative access credentials to be used when accessing the path (which is done by impersonation), or additionally add the path as a network resource.

By default, level Normal is set wich permits the folders plugins, log, userdata, webfiles, dashboard within the project directory for read/write access.
Log Level Specifies the detail level of logging which Codabix shall use when writing logfiles. Only those log entries are written that have at least a severity of this level. 'Off' means no logfiles are created.
Back-end Database Mode Specifies which back-end database to use. By default, Codabix uses an embedded database (SQLite) which doesn't need any additional configuration. The embedded database will be stored in the files codabixdb.db and codabixhistorydb.db in the specified project directory.
However, you can also use MySQL 8.0 or higher, MariaDB 10.3 or higher, or Microsoft SQL Server 2012 or higher as a back-end database. If you select “MySQL/MariaDB” or “Microsoft SQL Server”, you will need to fill in the settings grouped under the “MySQL/MariaDB/MSSQL Settings” category.

When creating a backup, the contents of the back-end database will be included in the backup. You can also migrate the current back-end database from SQLite to MySQL/MariaDB/MSSQL (or MySQL/MariaDB/MSSQL to SQLite) by creating a backup, switching the Database Mode and then restoring the backup.

Web Server Settings

Setting Name Description
Web Server Mode Specifies the mode of the embedded web server that Codabix uses in order to provide the Codabix Web Configuration, the REST/JSON interface, registered Script HTTP Handlers and optionally static files.
Kestrel is built on socket APIs and is used by default as it generally provides the best performance. When using HTTPS, SSL certificates need to be provided as PFX (PKCS #12) files (.pfx, .p12) and will be stored in the Codabix Settings file.
The Windows HTTP Server API is supported on Windows 10 Version 1607/Windows Server 2016 and higher, and allows to share ports with other IIS web sites. When using HTTPS, SSL certificates need to be placed in the Windows Certificate Store (see below). In order to use remote bindings, Codabix will need to be installed as a service.
Local HTTP Port Specifies the TCP at which the embedded web server listens for local connections. By default, Codabix uses the port 8181.

Note: When you use Windows HTTP Server API as Web Server Mode and you want to use ports ≤ 1024 (e.g. port 80), or you want to access the Codabix Web Configuration or the REST/JSON interface from other machines on the network, you need to install Codabix as a service (see below). In the latter case you will also need to open the “Service HTTP(S) Bindings” options and enable the option “Use the Local Port as remote HTTP Binding”.
Otherwise, only ports > 1024 are allowed and only the local machine can access Codabix via HTTP.
Service HTTP(S) Bindings You can enable HTTP and HTTPS bindings, containing the hostname, port and the SSL certificate (for HTTPS), for remote connections. This allows you to connect to Codabix from remote machines, optionally over an authenticated and encrypted TLS connection.

Note: To use a SSL certificate for Windows HTTP Server API Web Server Mode, it must be stored in the Personal or Web Hosting Certificate Store of the Local Computer account in Windows and you must have a private key for the certificate. Intermediate certificates (also called CA Cert) must be stored in the Intermediate Certificate Authorities Store.

To manage certificates in Windows, you can use MMC by running certlm.msc and then opening the Personal folder (or Web Hosting, resp.) for your certificate and the Intermediate Certificate Authorities folder for your intermediate certificates or you can use PowerShell by switching to the path Cert:\LocalMachine\My (or Cert:\LocalMachine\WebHosting) for your certificate and Cert:\LocalMachine\CA for your intermediate certificates.
Serve Static Web Files If enabled, the embedded web server will serve static files placed in the webfiles folder of the project directory for URLs starting with /webfiles/. This allows you in combination with the Script HTTP Handler feature to develop Web Apps served by Codabix (e.g for visualization).
Custom HTTP Redirect URL If not specified, requests for the root path (/) will be redirected to the Codabix Web Configuration. Alternatively, you can specify a custom redirect URL. This is useful if you want users to directly get to your custom Web App served by the embedded web server, when entering the Codabix address in their browser.

MySQL/MariaDB/MSSQL Settings

(applies only if Back-end Database Mode is “MySQL/MariaDB” or “Microsoft SQL Server”)

Setting Name Description
Hostname Specifies the hostname of the MySQL/MariaDB/MSSQL server. When using MSSQL and the port is empty, this will be interpreted as data soure (e.g. <ComputerName>\<InstanceName>). Otherwise, this is the hostname for TCP connections.
Port Specifies the TCP port of the MySQL/MariaDB/MSSQL server. Can be empty to use the default port (for MySQL/MariaDB) or to use the hostname as data source (for MSSQL).
Database Name Specifies the database name which Codabix shall use on the MySQL/MariaDB/MSSQL server. If the specified database does not exist, Codabix will automatically create the database and the necessary tables.
Login Name Specifies the username which Codabix shall use to connect to the MySQL/MariaDB/MSSQL Server.
Password Specifies the password for the username.

Installing Codabix as a Service

You can install Codabix as a service. This allows you to run Codabix automatically and permanently in the background (like on a Server) without having to explicitely start the Codabix application. Furthermore, this enables other machines in the network to access the Codabix instance per HTTP (e.g. opening the Codabix Web Configuration or using the REST/JSON interface), if you enable the option “Use the Local Port as remote HTTP Binding” in the “Service HTTP(S) Bindings” options.
Running Codabix as a service also allows to use HTTP Ports ≤ 1024, e.g. using Port 80.

After opening the Codabix settings dialog by clicking on the gear toolbar item at the top right (), it will show the section “Service Management” that allows you to install, start, stop and uninstall Codabix as a service:

You can install and start Codabix as a service by clicking the “Install & Start Service” button. This will show an UAC dialog (because installing a service requires administrator rights).

To uninstall the service, click the “Uninstall Service” button.

Note: When you change a setting like the project directory or the HTTP port while Codabix is running as a service, the service needs to be restarted (or reinstalled) to apply the new settings. This is indicated by the following dialog that lets you restart/reinstall the service:

Note: The service is configured to automatically restart after a failure. This ensures Codabix can restart in a clean, defined state after a serious error has occured.

License Management

Machine Code

When you order a Codabix license, you will need to provide the machine code for the machine where Codabix is running.

To get the machine code, in the Codabix application click on the key symbol (Codabix - License dialog) to open the license dialog. Then, click on the button “Copy Machine Code” to copy the local machine code into the clipboard.

 Codabix license dialog

System Requirements

Supported Operating Systems

Codabix for Linux is supported on the following Linux distributions:

  • Debian 9 (Stretch) or higher (x64, ARM64, ARM32)
    • including derivates such as Raspberry Pi OS (for Raspberry Pi)
  • Fedora 32 or higher (x64)
  • Ubuntu 18.04 or higher (x64, ARM64, ARM32)
  • OpenSUSE Leap 15.0 or higher (x64)

Hardware Requirements

  • Raspberry Pi:
    • Codabix for Linux (ARM64) can run on a Raspberry Pi 4 or newer (with a 64-Bit OS).
    • Codabix for Linux (ARM32) can run on a Raspberry Pi 2 or newer.
    • For optimal performance, we recommend running Codabix (ARM64) on a Raspberry Pi 4 (or newer) with 4 GB or 8 GB RAM, using an ARM64 OS.
  • Other machines:
    • Recommended: 64-bit Quad-Core CPU (x64/ARM64), 8 GB RAM, 64-Bit OS and Codabix

Back-end Database Requirements

By default, Codabix uses an embedded database (SQLite) which doesn't have any additional requirements.

However, if you plan on using MySQL, MariaDB, or Microsoft SQL Server as a back-end database, please make sure it is MySQL 8.0 or higher, MariaDB 10.3 or higher, or Microsoft SQL Server 2012 or higher.

Unsupported Features

Some features are currently not available in Codabix for Linux. This includes:

  • Windows-only plugins like Melsec QJ Device Plugin, H1 Device Plugin, AKLAN Device Plugin
  • Accessing OPC Classic (COM) Servers using the OPC UA Client Device Plugin
  • Impersonation for files with different credentials (or establishing of SMB network connections), e.g. for File Nodes or when using the CSV Exchange Plugin
  • GUI window (you can open the Codabix Web Configuration in a browser, but administrative tasks like setting the Project Directory, creating a backup etc. need to be done in the Codabix Shell console application)

Installing Codabix and First Start

Installing Codabix for Linux

To install Codabix for Linux, download the .setup file and execute the following command to make the file executable:
chmod +x codabix-<platform>-<release-date>-<release-version>.setup

Start the setup by typing:

sudo ./codabix-<platform>-<release-date>-<release-version>.setup

The setup will guide you through the installation.
Older installations of Codabix will not be removed to enable a later roll-back. The database backup that is needed for such a roll-back can be created during the setup.

First Start

To start the console-based Codabix Shell, run the following command:
  • Codabix should now be starting and ask for a project directory:

  • Enter the full path where you want to store the Codabix project directory (usually a folder in your home directory) (see Codabix Project Settings). Then, press enter two times to apply the settings and restart Codabix.

  • Codabix will now ask to reset the Admin password; please enter a new password here:

  • Now, you can open http://localhost:8181/config/ in a browser on your machine (if your Linux distribution was installed with GUI) to open the Codabix Web Configuration, or you can use http://<IP-address>:8181/config/ in a browser from another machine to access it over the network.

Run Codabix as a Service

Install Codabix as a Service

To install Codabix as a service, start the Codabix Shell by executing the following command:
  • Choose the option 6 from the command line menu to invoke the Service Management:

  • By choosing option 1 in the Service Management you can now install and start Codabix as a Service:

  • After successfully starting the service you will see the status Service is running on the command line:

  • Now you can close the Codabix Shell with 9 and the service will keep running in background.
  • From now on the service will be automatically started in case of a reboot of the operating system.

Status of the Codabix Service

To retrieve the current status of the Codabix Service (Running, Stopped) start the Codabix Shell:

The current status of the service will now be displayed:

(Re-)start, stop and uninstall the Codabix Service

In order to (re-)start, stop, or uninstall the Codabix Service open the Codabix Shell:
  • Call the Service Management via option 6
  • Now choose the requested funcion:

License Management

Machine Code

When you order a Codabix license, you will need to provide the machine code for the machine where Codabix is running.

To get the machine code, execute the following command on the command line (bash):

codabix --machinecode

This will output the local machine code to the terminal, for example:

$ codabix --machinecode

Alternatively, you can display the machine code in the Codabix Shell application, by entering license in the main menu to open the license management. The local machine code will be displayed at the top:

This section describes the necessary steps, to put the Codabix Siemens IOT2050 Image into service.

Content of the image

For this image the Siemens IOT2050 Example Image was used as base image.

Additionally the following components have been installed:

  • Components for DNS Discovery
    • Avahi Daemon
      • This service allows the so-called DNS-SD (DNS Service Discovery) based on the Apple Bonjour Protocol. This way the device can be discovered in the local network by its hostname and the “local” domain without the need to know its IP address.
    • Automatic hostname
      • During startup an automatic hostname which is based on the serial number of the device is generated. So every device gets a unique hostname that can be determined with the serial number which is printed on the device housing.
  • Codabix + Codabix service
  • Set root password: codabix-iot

Writing the image

For writing the image to an SD card we recommend the following tool:

Putting into serivce

After writing the image to the SD card, put the card into the SD card slot of the IOT2050 device and connect the device to the power supply. To enable access via network, the device needs to be part of the same network as your computer.

Automatic Hostname

The hostname of the device is generated according to the following pattern:


For the next steps we assume that the device has the serial number M4A98757. So make sure to exchange it with the actual number of your device.

serialNumber = M4A98757
hostname = codabix-iot-M4A98757

To check if the device is accessible you can execute the following command on the command line:

Attention: The Apple Bonjour service has to be installed on your system for the next steps to work.
$ ping codabix-iot-M4A98757.local

If this command is not successful either the IOT2050 has not yet completely booted or it is not accessible from your network.

Accessing the Codabix web configuration

If the ping command has been successful you can access the Codabix web configuration in a browser under the URL http://codabix-iot-M4A98757.local:8181.

Login data:

  • User: admin
  • Passwort: codabix-iot

Access via SSH

To access the device via SSH, execute the following command on a command line:

$ ssh root@codabix-iot-M4A98757.local

Login data:

  • User: root
  • Passwort: codabix-iot

1) , 2)
Update KB3063858 (x64 or x86) is required.

Additionally, to use licenses with a machine code, the Windows Management Framework 3.0 (KB2506143) must be installed.