Install BRIX AI in an air-gapped environment

This article describes how to install BRIX AI in an air-gapped environment using Docker Swarm. This deployment option is suitable for production environments because it allows you to scale microservices as your load grows.

This setup requires a private image registry. We recommend using Harbor. For details on how to set it up, see Install Harbor for BRIX AI.

The installation process for BRIX AI consists of the following steps:

1. Copy installation files to the air-gapped environment.
2. Push images to the private Docker registry.
3. Configure the private registry.
4. Install BRIX AI.

Prerequisites for air-gapped installation

Make sure that:

• On the machine with internet access, the following requirements are met:
  • Linux OS (Ubuntu 18.04+, CentOS 7+, or similar).
  • At least 20 GB of free disk space.
  • curl or wget is installed.
  • Root or sudo permissions are granted.
  • You have downloaded installation files and configured environment variables.
• On the air-gapped machine:
  • Docker Swarm is initialized.
  • Access to your private Docker registry is available.

Step 1. Transfer files to the air-gapped environment

Copy the elma-cortex-X.Y.Z folder to your air-gapped server, where X.Y.Z is the BRIX AI version number. You can use any file transfer method, such as a USB drive or SCP if a secure connection is available.

Example using SCP:

scp -r elma-cortex-X.Y.Z user@air-gapped-server:~/

Step 2. Push images to the private registry

On the air-gapped server, push the Docker images to your private registry. The push method depends on your registry settings and the type of certificate used.

Important: If you use a non-standard port, specify it in the address in the --uri parameter.

Push images using a trusted certificate

If your registry uses a certificate issued by a public Certificate Authority (CA) or the certificate is added to the trusted list on the server, use standard commands:

cd ~/elma-cortex-X.Y.Z
./cortex-offline-swarm.sh --push \
  --uri your-registry.example.com/elma-cortex \
  --creds admin:your-password

Add the CA root certificate to trusted

You can add your Certificate Authority (CA) root certificate to the trusted list by specifying the path to its directory. This ensures a secure TLS connection with server authentication:

mkdir -p ~/certs
cp ca.crt ~/certs/
 
./cortex-offline-swarm.sh --push \
  --uri your-registry.example.com/elma-cortex \
  --creds admin:your-password \
  --cert-dir /path/to/certs

Disable TLS verification for a self-signed certificate

To quickly push images with a self-signed certificate, you can disable TLS verification:

./cortex-offline-swarm.sh --push \
  --uri your-registry.example.com/elma-cortex \
  --creds admin:your-password \
  --tls-verify false

Note that this method does not provide a secure connection.

Step 3. Configure the private registry

1. Go to the directory containing Docker Swarm files:

cd swarm-files

2. Specify your private registry address in the .env file. If you use a non-standard port, separate it with a colon:

IMAGE_REPOSITORY=your-registry.example.com:5000/elma-cortex

Step 4. Install BRIX AI

1. If you use a private registry that requires authentication, log in to Docker:

docker login your-registry.example.com

2. Run the installation script:

chmod +x install.sh
./install.sh

Update BRIX AI

When a new version of BRIX AI is released, save your current configuration and perform the update. For details, see Update BRIX AI in an air-gapped environment.

Uninstall BRIX AI

To uninstall BRIX AI in an air-gapped environment, follow the steps in Install BRIX AI using Docker Swarm.

Troubleshoot BRIX AI installation

Below are common issues that may occur during the installation of BRIX AI in an air-gapped environment.

"Permission denied" error when running scripts

Make sure the scripts are executable:

chmod +x cortex-offline-swarm.sh install.sh manage-certs.sh

Image push error

1. Check your registry credentials:

docker login your-registry.example.com

2. Check TLS settings. For self-signed certificates, use the --tls-verify false parameter.
3. Make sure there is available disk space on the registry server.

Services fail to start

1. Verify that all images are pushed:

docker images | grep your-registry.example.com

2. Verify that the correct path to the image repository is specified in the .env environment variables file for the IMAGE_REPOSITORY parameter.
3. Verify that Docker has permissions to pull from your registry:

docker pull your-registry.example.com/elma-cortex/elma-assistant/llm-service/gamma-apps:X.Y.Z 

Command reference for air-gapped installation

When installing BRIX AI, the cortex-offline-swarm.sh script is used. For non-standard installation scenarios, see all available commands for it.

Script usage:

./cortex-offline-swarm.sh <command> <flags>