Skip to content

Installing AI Controller on Linux

This comprehensive guide provides detailed instructions for installing AI Controller directly on a Linux environment.
Upon completing the steps in this guide, AI Controller will be installed and ready for set up by following the details in the Initial Configuration guide.
The expectation is that the steps in this document will be carried out by a system administrator, where as the steps in the First Time Setup guide would be completed by an administrator of the AI Controller application; while this can be the same user, it does not need to be.

Prerequisites

Before proceeding with a Linux installation, ensure your system meets the requirements outlined in the System Requirements document.

Key requirements for Linux installation:

  • Ubuntu 22.04/24.04 LTS or compatible Linux distribution
  • Root or sudo access
  • MySQL 8.0+
  • Redis 6.0+

This guide provides commands and steps for installing onto a Ubuntu OS. If a different Linux distribution is running the exact commands to run might be different to those listed.

Pre-Installation Setup

1. System Preparation

Update your system and install essential packages:

# Update package lists and upgrade existing packages
sudo apt update && sudo apt upgrade -y

# Install basic dependencies - some/all are likely already installed.
sudo apt install -y build-essential curl wget gnupg2 software-properties-common \
    apt-transport-https ca-certificates lsb-release openssl unzip

2. Install MySQL Database

If there is already an installation of MySQL that the AI Controller application can use, this step can be skipped.
Note that MySQL does not need to be running on the same machine as AI Controller, although access to it will be faster if it is. If using an existing MySQL installation, credentials will be required for a user that has permissions to create both Databases and Users, and then to grant privileges to the created user.

Follow these steps to install MySQL:

  1. Install MySQL by running: 
    sudo apt install -y mysql-server
  2. Set up the new MySQL instance by running: 
    sudo mysql_secure_installation
  3. Follow the prompts to set a root password and secure your MySQL installation.

3. Configure MySQL for remote access (if needed):

It's possible a remote connection to the MySQL database is wanted. Before this will be allowed, the MySQL configuration needs to be updated as described below. Note that this is not required for normal operation of AI Controller.

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Change the bind-address line to: 

bind-address = 0.0.0.0

Restart MySQL: 

sudo systemctl restart mysql

4. Create Database for AI Controller

Before running AI Controller, a database is needed for it to use. Follow the steps below to do this:

    • The command sudo mysql -u <admin user> -p can be used * Replace with 'root' if MySQL has been installed with the defualt options. If another user is used, that account will need privileges for creating databases and users.
  2. Run these SQL commands to create the database: 
    -- Create the database
CREATE DATABASE aic;
-- Create a user for AIC
CREATE USER 'aicAdmin'@'<host>' IDENTIFIED BY '<Password>';
-- Grant that user privileges
GRANT ALL PRIVILEGES ON aic.* To 'aicAdmin'@'<host>';
-- Apply the privilege changes
FLUSH PRIVILEGES;
    • The name given to the database can be anything, but 'aic' is the default expected by the AI Controller application.
    • The name given to the user can also be anything. It defaults to aicAdmin in the AI Controller configuration.
    • The <host> should be replaced with the hostname of the machine on which the AI Controller application will be running, or 'localhost' if MySQL and AI Controller will be running on the same machine.
    • <Password> should be replaced with a suitably strong password.
    • Remember the settings used, as they will be needed later.
  3. Disconnect from MySQL by typing ‘exit’

5. Install Redis

If there is already a Redis instance that the AI Controller application can use, this step can be skipped.
Note that Redis does not need to be running on the same machine as AI Controller, although access to it will be faster if it is. To install Redis, run the following command: 

sudo apt install -y redis-server
Once installed, set it to start on system boot and start the server with these commands: 
sudo systemctl enable redis-server
sudo systemctl start redis-server

6. Create AI Controller Service User

It's recommended to run AI Controller under a dedicated service account. The commands below also set the AI Controller installation/home directory to be /opt/aic. AI Controller can be installed into any location, so this can be updated prior to running the commands if /opt/aic is undesirable.

# Create the AI Controller user and group
sudo groupadd aic
sudo useradd -r -g AI Controller -d /opt/aic -s /bin/bash aic

# Create installation directory
sudo mkdir -p /opt/aic
sudo chown aic:aic /opt/aic

AI Controller Installation

With the setup of MySQL and Redis complete, the AI Controller application can be installed and run.
When creating an AI Controller subscription, an e-mail will be sent to the registered e-mail address containing two items of data important for installation and set up:

  1. A download link where the latest version of the AI Controller installation archive can be downloaded
  2. The Licence Key

The first step to installing AI Controller, is to download the latest version of the AI Controller installation archive using that download link. The Licence Key will be used when following the steps in the Initial Configuration guide.
The download archive will be named AIC.<version>.zip, where version is the version number of the AI Controller application that has been downloaded.

Once downloaded, follow these steps to unpack the archive and set up the application for first use:

  1. Choose where the AI Controller application should be installed, and unzip the archive there.
    • Any location can be chosen, but /opt/aic is suggested.
  2. Generate TLS certificates for the machine running AI Controller
    • See below for details
  3. Setup the AI Controller server configuration file
    • See below for details
  4. Set file permissions
    • It is important that only authorised users have access to the AI Controller installation folder, particularly the server configuration file.
    • Set file permissions appropriately for your organisation so that access is restricted correctly.
  5. Create a Service to automatically start AI Controller (optional)
    • See below for details
  6. Create the AI Controller database schema
    • See below for details.

Generate TLS Certificates

For HTTPS communication AI Controller requires appropriate certificates. Self-signed certificates are OK, and can be generated using OpenSSL as described below. However, most browsers will consider a self-signed certificate unsafe for HTTPS communication and display their 'Connection not private' page asking for confirmation before proceeding. As such, it is recommended to use a certificate from a trusted certificate authority, or to use AI Controller in HTTP mode (see Setting up HTTP use below).
The AI Controller installation archive comes with a self-signed certificate for 'localhost' that can be used if required.

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /opt/aic/ca-certificates/localhost.key \
  -out /opt/aic/ca-certificates/localhost.crt \
  -subj "/CN=localhost/O=AIC/C=US"

sudo chmod 600 /opt/aic/ca-certificates/localhost.key

Set up Configuration File

The configuration settings for the AI Controller application are found in the <AIC install directory>/configuration/server.cfg file. The default file contains the settings that are necessary to run AI Controller, but there are many other settings that can be configured as needed. See Server Configuration Options for further details.

The default configuration file should be customised prior to running AI Controller for the first time. Specifically, the Username and Password fields will need to be changed.
In the case that MySQL or Redis are not running using the default ports/settings, or on the same machine as AI Controller, the settings related to these will need to be updated. See Database Configuration Options.

Set File Permissions

Ensure all files have the appropriate ownership and permissions:

sudo chown -R aic:aic /opt/aic
sudo chmod 755 /opt/aic/bin/AIC
sudo chmod 755 /opt/aic/bin/MigrationsRunner
sudo chmod 600 /opt/aic/configuration/server.cfg

Configure Systemd Service

It may be desirable to have AI Controller start as a Service during system boot.
To do this follow these steps:

  1. Create a systemd service file for AI Controller: 
    sudo nano /etc/systemd/system/aic.service
  2. Add the following content: 
    [Unit]
Description=AI Controller (AIC) Service
After=network.target mysql.service redis-server.service
Wants=mysql.service redis-server.service

[Service]
Type=simple
User=aic
Group=aic
WorkingDirectory=/opt/aic
ExecStart=/opt/aic/bin/AIC
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
TimeoutStartSec=120

# Security enhancements
PrivateTmp=true
ProtectHome=true
ProtectSystem=full
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
  3. Enable and start the service: 
    sudo systemctl daemon-reload
sudo systemctl enable aic
sudo systemctl start aic

Create Database Schema

Prior to starting AI Controller for the first time, the database tables, and default data need to be created. The utility called MigrationsRunner is provided for this purpose. This utility should also be used when upgrading to a new version of AI Controller to perform any database schema updates that are needed.

To create/update the database schema open a command prompt, change into the AI Controller installation directory and run: 

cd /opt/aic
sudo -u aic ./bin/MigrationsRunner --env=prod
The first time the MirgrationsRunner is executed should produce output very similar to this: 
Using calculated base path: <AIC install directory>/
Loading server configuration at : <AIC install directory>/configuration/server.cfg
__SchemaVersions table not present in DB. Running all Migrations.
Migration MIGRATION-0001.all.INITIAL.sql applied successfully.

Additional Tasks

Setting up HTTP use

While AI Controller defaults to using HTTPS communication, it can be configured to run in HTTP mode.
This applies only to communication to AI Controller; the requests that AI Controller sends out to Providers would still be TLS encrypted if the Provider is an HTTPS provider.
To set enable HTTP mode in AI Controller:

  1. Open the <AIC install directory>/configuration/server.cfg file
  2. Add the ServerConfiguration.Security.SSL.Enabled element and give it the value 'false': 
    <Security>
    <SSL>
        <Enabled>false</Enabled>
    </SSL>
</Security>
    After doing this, the default server.cfg file would look like this prior to first starting AIC: 
    <?xml version="1.0" encoding="UTF-8" ?>
<ServerConfiguration>
    <ServerInfo>
        <!-- The hostname where AIC will be running -->
        <HostName>localhost</HostName>
        <!-- The port on which AIC should listen -->
        <Port>9090</Port>
    </ServerInfo>
    <DatabaseConfiguration>
        <!-- The IP address of the machine running the MySQL database for AIC -->
        <DBHost>127.0.0.1</DBHost>
        <!-- The port on which the MySQL database is accessed -->
        <DBPort>3306</DBPort>
        <!-- The MySQL user name created for accessing the AIC database -->
        <Username>aicAdmin</Username>
        <!-- The password for the above user -->
        <Password>changeme</Password>
    </DatabaseConfiguration>
    <Security>
        <SSL>
            <Enabled>false</Enabled>
        </SSL>
    </Security>
</ServerConfiguration>
    See the Server Configuration Options guide for further details of the settings available for use within the server.cfg file.

Firewall Configuration

It may be necessary to specifically configure the Firewall in use to allow communication with AI Controller, or to unblock the application for any end point protection systems in place.

The AI Controller frontend and API defaults to being served on port 9090, using HTTPS (TCP protocol).

AI Controller makes HTTP/HTTPS (TCP) connections to the configured providers (e.g. OpenAI), either using the default port (80/443) or the configured ports in the provider URL.
If MySQL and/or Redis are being served on different hosts, AIC will make connections to MySQL (defaults to port 3306) and Redis (defaults to port 6379). It may be nessesary to open the ports on these hosts for AIC to be able to connect to them.

Backups

AI Controller does not automatically back up any of the data stored within the database.
It is recommended that regular database dumps are performed to backup the content of the database. The MySQL utility mysqldump can be used to do this. See the MySQL documentation for details.

Start AI Controller

Note that AI Controller will already be running if the steps to set up a Systemd Service were completed. With all installation steps complete, AI Controller is ready to be started for the first time. To do this, open a terminal and navigate to the AI Controller installation directory and:

  1. Run the AI Controller executable: 
    sudo -u aic bin/AIC
  2. Once started, the console will display some output like this: 
    ********************************************************************
The AIC vX.Y.Z (c) YYYY QA Systems GmbH
********************************************************************
Initialisation started.
Using calculated base path: <AIC install directory>/
Loading server configuration at : <AIC install directory>/configuration/server.cfg
Finished initialisation.
Starting AIC web service.
********************************************************************
AIC Web Service started at : localhost:9090
ctrl+c to kill
  3. Open your browser and navigate to https://localhost:9090 to display the AIC login page.
  4. The default user credentials are
    • Username: admin
    • password: admin

With this complete, AI Controller is up and running and ready for the first time set up and configuration specific to your organisation and use.

Next Steps

Updated: 2025-05-21