Skip to content

Installing AI Controller with Docker

This guide provides step-by-step instructions for deploying AI Controller using Docker. Docker is the recommended deployment method for most environments. 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.

Prerequisites

Before installing AI Controller with Docker, ensure your system meets the minimum requirements. For detailed specifications, see the System Requirements document.

Key requirements for Docker installation: - Docker Engine 24.0+ and Docker Compose 2.0+ - Internet access to pull Docker images

Installation Steps

1. Create Installation Directory

Create a directory to store your AI Controller configuration and data. All examples and configuration in this guide will assume /opt/aic but you can substitute any suitable path:

mkdir -p /opt/aic
cd /opt/aic

2. Extract Installation Archive

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 License Key

Download the latest version of the AI Controller installation archive using that download link. The License 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, unpack the archive into the installation directory:

unzip AIC.<version>.zip

3. Install TLS Certificates

For HTTPS communication, AI Controller requires appropriate certificates. Self-signed certificates can be generated using OpenSSL as described below, or you can install your own certificate. Note that 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 in the Linux install guide).

The AI Controller installation archive comes with a self-signed certificate for 'localhost' that can be used if required, or one can be generated as follows:

docker run -ti --rm -v /opt/aic:/opt/aic alpine/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"

By default, AI Controller looks for a certificate called localhost.crt and key called localhost.key in the ca-certificates directory of the installation. This can be modified in the SSL section of the Server Configuration.

4. Set up Configuration File

The configuration settings for the AI Controller application are found in the <AIC install directory>/configuration/server.cfg file. See Server Configuration Options for further details on the configuration file.

We need to modify the DatabaseConfiguration to set the details for the MySQL and Redis services we will start later.

  • Set the DBHost field to aic-mysql. This will be the name of the MySQL service we will start later.
  • Set the Username field to aicAdmin (or another username if you want to configure your MySQL database to use a different one).
  • Set the Password field to a secure unique password. DO NOT leave it as changeme.
    • You can generate a password by running docker run -ti --rm alpine/openssl rand -hex 32.
  • Add (or set) the RedisHost field to aic-redis. This will be the name of the Redis service we will start later.

Afterwards, your configuration should look something like: 

<?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>aic-mysql</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>
        <RedisHost>aic-redis</RedisHost>
    </DatabaseConfiguration>
</ServerConfiguration>

In the case that MySQL or Redis are not running using the default ports/settings, or on the same host as AI Controller, the settings related to these will need to be updated. See Database Configuration Options.

5. Create the Docker Compose File

The docker compose file will create a container to run AI Controller and the necessary services (MySQL, Redis) and connect them up with a docker network. You do not have to use docker compose, but it simplifies the setup:

Be sure to set the MYSQL_PASSWORD: to the password you set earlier in the server.cfg. If you are not running AI Controller on the default port of 9090, be sure to update the port: mapping.

Create the file /opt/aic/docker-compose.yml with the following contents: 

services:
    mysql:
        image: mysql:8
        container_name: aic-mysql
        environment:
            MYSQL_RANDOM_ROOT_PASSWORD: "yes"
            MYSQL_DATABASE: aic
            MYSQL_USER: aicAdmin
            MYSQL_PASSWORD: changeme
        volumes:
            - /opt/aic/mysql:/var/lib/mysql
        networks:
            - aic_network
        healthcheck:
            test: mysqladmin ping -h localhost -u $$MYSQL_USER --password=$$MYSQL_PASSWORD
            timeout: 20s
            retries: 10
    redis:
        image: redis:latest
        container_name: aic-redis
        networks:
          - aic_network
    ubuntu:
        image: ubuntu:24.04
        container_name: aic-ubuntu
        ports:
            - "9090:9090"
        volumes:
            - /opt/aic:/opt/aic
        networks:
            - aic_network
        tty: true
        stdin_open: true
        environment:
            - AICPATH=/opt/aic
            - DEBIAN_FRONTEND=noninteractive
        working_dir: /opt/aic/bin
        command: >
            sh -c "./MigrationsRunner --env=prod && ./AIC"
        depends_on:
            mysql:
                condition: service_healthy
        healthcheck:
            test: ["CMD", "pgrep", "AIC"]
            interval: 10s
            timeout: 5s
            retries: 3

networks:
  aic_network:
    name: aic_network

6. Set File Permissions

Ensure all files have the appropriate ownership and permissions for security. Specifically, the configuration and docker-compose.yml should only be readable by trusted users as it contains credentials and secrets.

e.g. on Linux as the trusted user: 

sudo chmod 755 /opt/aic/bin/AIC
sudo chmod 755 /opt/aic/bin/MigrationsRunner
sudo chmod 600 /opt/aic/configuration/server.cfg
sudo chmod 600 /opt/aic/docker-compose.yml

Start AI Controller

From the installation directory, run:

docker-compose up -d

You should see output containing: 

aic-ubuntu | __SchemaVersions table not present in DB. Running all Migrations.
aic-ubuntu | Migration MIGRATION-0001.all.INITIAL.sql applied successfully.
aic-ubuntu | ********************************************************************
aic-ubuntu | The AI Controller v1.0.0 (c) 2025 QA Systems GmbH
aic-ubuntu | ********************************************************************
aic-ubuntu | Initialisation started.
aic-ubuntu | Using AICPATH environment variable: /opt/aic
aic-ubuntu | Loading server configuration at : /opt/aic/configuration/server.cfg
aic-ubuntu | Finished initialisation.
aic-ubuntu | Starting AIC web service.
aic-ubuntu | ********************************************************************
aic-ubuntu | AIC Web Service started at : localhost:9090
aic-ubuntu | ctrl+c to kill
aic-ubuntu | ********************************************************************

Access the AI Controller web interface at https://localhost:9090

Log in with the default credentials: - Username: admin - Password: admin

Next Steps

Troubleshooting

Container Fails to Start

If any container fails to start:

docker-compose logs [service_name]

Review the logs for error messages and refer to the Troubleshooting section.

Database Connection Issues

If the AI Controller service cannot connect to the database, you may see the following messages:

aic-ubuntu | Using AICPATH environment variable: /opt/aic
aic-ubuntu | Loading server configuration at : /opt/aic/configuration/server.cfg
aic-ubuntu | 29-05-2025 13:58:25 : ConnectionManager : ERROR: Failed to get the session from session pool : Connection attempt failed
  1. Verify MySQL container aic-mysql is running with docker ps
  2. Check database credentials in server.cfg match those in the docker-compose.yml
  3. Ensure the MySQL port is accessible

Web Interface Not Accessible

If you cannot access the web interface:

  1. Verify all containers are running with docker ps
  2. Check the ports configured in server.cfg and docker-compose.yml
  3. Verify TLS certificates are correctly configured
  4. Restart the services with docker-compose down && docker-compose up -d

Upgrading AI Controller

To upgrade your Docker-based AI Controller installation:

  1. Stop the services. 

    docker-compose down

  2. Backup your current installation, especially the database files in /opt/aic/mysql.

  3. Update the files in the /opt/aic directory with the new installation archive.

  4. Check the latest documentation for any changes required to the docker-compose.yml file.

  5. Pull the latest images: 

    docker-compose pull

  6. Start the services: 

    docker-compose up -d

Updated: 2025-05-29