# Install BRIX AI in an air-gapped environment

> [HTML Version](cortex-air-gapped.html)

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](https://goharbor.io/). For details on how to set it up, see [Install Harbor for BRIX AI](cortex-harbor.md).

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

1. [Copy installation files to the air-gapped environment](#copy-installer-files).

2. [Push images to the private Docker registry](#push-images-to-registry).

3. [Configure the private registry](#configure-private-registry).

4. [Install BRIX AI](#install).

## 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](cortex-download-installer.md) and [configured environment variables](cortex-environment-variables.md).

- 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](#trust-certificate) 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](update-cortex-air-gapped.md).

## Uninstall BRIX AI

To uninstall **BRIX AI** in an air-gapped environment, follow the steps in [Install BRIX AI using Docker Swarm](cortex-docker-swarm.md).

## 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>

| | | |
|------|------|------|
| ````<br>**Command** | **Description** | **Parameters** |
| \[OBJECT\] | Download Docker Swarm files and Docker images.<br> | `\--dir <PATH>`: The directory where files are downloaded. Default: `elma-cortex-X.Y.Z`, where `X.Y.Z` is the **BRIX AI** version number. |
| \[OBJECT\] | Push images to a private registry. | - `--uri <URI>`: Registry URI. Required parameter.<br>- `--dir <PATH>`: Directory containing images.<br>- `--creds <USER:PASS>`: Registry credentials.<br>- `--cert-dir <PATH>`: Path to TLS certificates.<br>- `--tls-verify <BOOL>`: Verify TLS. Default is `true`. |