Installing Codabix

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

The current version of Codabix for Windows requires Windows 8 or Windows Server 2012, or higher.
We recommend to run the 64-bit versions of Codabix for stability reasons.

System Requirements

Supported Operating Systems

Codabix for Windows is supported on the following operating systems (architectures x64, x86, and ARM64):

Windows Version Workstation Operating System Server Operating System
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.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)
10.0.18363 Windows 10 Version 1909 (November 2019 Update)
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)
10.0.19043 Windows 10 Version 21H1 (May 2021 Update)
10.0.19044 Windows 10 Version 21H2
10.0.20348 Windows Server 2022 (Option “Server with Desktop Experience”, or “Server Core” with Server Core App Compatibility FOD installed)
10.0.22000 Windows 11 Version 21H2

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):

"%ProgramFiles%\TIS\Codabix\codabix-ui.exe"

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):

"%ProgramFiles%\Traeger\Codabix\codabix-ui.exe"

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 io.directory 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 10 (Stretch) or higher (x64, ARM64, ARM32)
    • including derivates such as Raspberry Pi OS (for Raspberry Pi)
  • Fedora 33 or higher (x64)
  • Ubuntu 18.04 or higher (x64, ARM64)
  • 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, installing the service 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
  • 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:
codabix
  • 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:
codabix

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:
codabix
  • 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
U7f3lqK5bG04fIVUNX5yhWgNlG6PnSKbvHuY6Ml610gAAgAA9+w5OG0p0AFgKyfQPVjBO9rId87pLs29nC+CHQ==


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: