Installing CoDaBix

CoDaBix is currently available for Windows operating systems, as well as for Linux, and Raspbian running on a Raspberry Pi.

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 x64 (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 Version 1607 (Winodws 10 [IoT] Enterprise 2016 LTSB) Windows Server 2016 (Option “Server with Desktop Experience”)
10.0.15063 Windows 10 Version 1703 (Creators Update)
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 Version 1809 (October 2018 Update) Windows Server 2019 (Option “Server with Desktop Experience”, or “Server Core” with Server Core App Compatibility FOD installed)
Windows Server, version 1809 (with Server Core App Compatibility FOD installed)
10.0.18362 Windows 10 Version 1903 (May 2019 Update) Windows Server, version 1903 (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)

Necessary Components

CoDaBix requires the .NET Framework 4.7.2 or higher, which is included in Windows 10 Version 1803 (April 2018 Update) and Windows Server 2019 and onwards.
For older Windows versions, please install the .NET Framework 4.7.2 3).

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 5.7 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.

Hardware Requirements

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

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%\Traeger\CoDaBix\CoDaBix.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 Settings

CoDaBix provides a number of settings which you can configure. 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 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.
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 the project directory 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.
File Access Security Within CoDaBix, you 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 and has local or network access to the CoDaBix Web Configuration 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 and 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 5.7 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.
HTTP.sys uses the Windows HTTP Server API and is supported (and recommended) on Windows 8/Windows Server 2012 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).
Kestrel is built on socket APIs and will be used on non-Windows OSes and on Windows 7/Windows Server 2008 R2. Additionally, Kestrel allows to use ports ≤ 1024 and remote access without having to install CoDaBix as a service. 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.
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 HTTP.sys 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 When running CoDaBix as a service (or when using Kestrel as Web Server Mode), you can specify various 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 HTTP.sys 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 (x64) is supported on the following Linux distributions for the AMD64 platform:

  • Debian 9 (Stretch) or higher
  • Fedora 29 or higher
  • Ubuntu 16.04 or higher
  • OpenSUSE Leap 15.0 or higher

CoDaBix for Raspberry Pi is supported on the following Raspbian operating systems for the ARM32/ARM64 platform:

  • Raspbian 9 (Stretch) or higher

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 5.7 or higher, MariaDB 10.3 or higher, or Microsoft SQL Server 2012 or higher.

Hardware Requirements

CoDaBix for Raspberry Pi:

  • Raspberry Pi 2 or 3

Unsupported Features

Some features are currently not available in CoDaBix for Linux and Raspberry Pi. 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)
  • S7 Configurator (you can edit the CoDaBix.S7DevicePlugin.Settings.xml file manually, or copy it to a Windows PC with CoDaBix for Windows installed for editing)

Installing CoDaBix and First Start

Installing CoDaBix for Linux or Raspberry Pi

To install CoDaBix for Linux (x64) or CoDaBix for Raspberry Pi, 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 (the parameter –remoteHttp specifies that the CoDaBix web server should allow external HTTP connections):
codabix --remoteHttp
  • 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 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:


1) , 2)
Some features are available only when running on Windows 8 / Windows Server 2012 or higher. This includes using HTTP.sys as Web Server Mode in order to share a port with other IIS websites and using HTTPS Bindings for individual hostnames (SNI).
3)
If the installation of .NET 4.7.2 on Windows 7 SP1 or Windows Server 2008 R2 SP1 fails with the error “A certificate chain could not be built to a trusted root authority”, please connect your machine to the internet and ensure that all Windows Updates are installed. Please also ensure that the group policy “Turn off Automatic Root Certificates Update” has not been enabled.

If the installation of .NET on Windows 7 or Windows Server 2008 R2 fails with the error “The .NET Framework 4.x is not supported on this operating system”, you will first need to install Service Pack 1.

Users of Windows 8.1 or Windows Server 2012 R2 may need to install KB2919442 (x86 or x64) and KB2919355 (x86 or x64) (in that order), before they can install a new .NET version.