Installation Guide

This guide describes the installation of VARIOS AI on your own Linux server. VARIOS AI runs as a Docker Compose installation; you receive the installation files docker-compose.yml, .env, varios.sh and update_version from the VARIOS AI team. Check the system requirements beforehand.

Allow half a working day for the technical installation. Most of the time goes into coordination with the DNS, firewall and identity teams, so plan this in advance.

Installation

Prepare the server

Install the current updates of your distribution, enable time synchronization and set up the firewall according to the system requirements. A correct clock is mandatory for sign-in and certificates.

sudo timedatectl set-ntp true

Install Docker

Install Docker Engine and Docker Compose v2 following your distribution’s instructions or with the official script, and enable autostart.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker
docker compose version

Install gVisor (optional, recommended)

The code interpreter runs code in a sandbox. gVisor additionally shields this sandbox from the server’s kernel. Install runsc following the official guide and register it as a Docker runtime: Installation and Docker Quick Start.

docker info --format '{{.Runtimes}}'                      # contains runsc
docker run --rm --runtime=runsc alpine:3 dmesg | head -3  # shows gVisor messages

Create the installation directory

Create a directory, for example /docker/variosai, and copy the four installation files into it. The database, files and backups will later be created in this directory as well, so include it in your backups.

sudo mkdir -p /docker/variosai
cd /docker/variosai
chmod +x varios.sh

Adjust .env

The delivered .env contains defaults. Adjust at least these values:

Variable	Meaning
`PROJECT_DOMAIN`	Domain under which users open VARIOS AI, without `https://`
`ACME_EMAIL`	E-mail address for Let’s Encrypt, only with automatic certificate
`POSTGRES_PASSWORD`	Your own strong database password
`REDIS_PASSWORD`	Your own strong password for the cache (Redis); required, the installation does not start without it
`OIDC_*`	Credentials of your identity provider, see Setting up Microsoft Entra ID or Setting up Keycloak
`ADMIN_GROUP_NAME`, `SUPERADMIN_GROUP_NAME`, `COMPLIANCE_ADMIN_GROUP_NAME`	Names of the roles or groups in the identity provider whose members receive administrator rights. There is no variable for regular users; you control who can sign in in the identity provider.
`SCIM_*`	User synchronization, see the Entra or Keycloak page
`CODE_INTERPRETER_API_TOKEN`, `CODE_INTERPRETER_WORKER_TOKEN`	Two different random values of at least 32 characters for the code interpreter; without them the code interpreter does not start
`DOCKER_RUNTIME`	`runsc` if you installed gVisor; otherwise leave it empty

Generate both tokens directly in .env:

sed -i '/^CODE_INTERPRETER_\(API\|WORKER\)_TOKEN=/d' .env
echo "CODE_INTERPRETER_API_TOKEN=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 64)"    >> .env
echo "CODE_INTERPRETER_WORKER_TOKEN=$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 64)" >> .env

The .env contains passwords and secrets. Do not share it and include it in every backup.

Decide on HTTPS

By default, VARIOS AI obtains the certificate automatically from Let’s Encrypt. For this, PROJECT_DOMAIN must point to the server and ports 80 and 443 must be reachable from the internet. No further preparation is needed; the certificate files are created automatically on first start.To use your own certificate instead, follow Configuring a Custom HTTPS Certificate. For a reverse proxy of your company in front of VARIOS AI, please contact support.

You receive the credentials from the VARIOS AI team. The login is stored on the server and must be repeated after moving to a new server. Log in with sudo, because the update helper varios.sh runs as a systemd service under root and uses the login stored for root. If you also run docker as your own user without sudo, log in without sudo as well.

sudo docker login registry.varios-ai.com

Start the services

docker compose pull
docker compose up -d
docker compose ps

The first start downloads all images and takes a few minutes. Afterwards, all services should be listed as running or healthy.

Set up the database

docker compose exec php ./update.sh

The script creates the database, loads the template library and prepares the application. The first run can take 15 to 60 minutes; do not abort it. It also checks whether the processor supports AVX2.

Afterwards, VARIOS AI is reachable at https://<PROJECT_DOMAIN>.

Sign in with an account that carries the role from SUPERADMIN_GROUP_NAME in the identity provider. Enter the license key from the VARIOS AI team under Administration → Settings → System Information.

Set up the update helper

varios.sh performs the updates you trigger in the interface. Set it up as a systemd service so that it keeps running after a reboot, see systemd Service.

After each update, the update helper removes unused Docker images and volumes of the entire server. Do not run other Docker applications on the same server.

Adjust code interpreter limits

Default values apply to the code interpreter’s input and result files. To change them, add the variables to .env. docker-compose.yml passes them on to all affected services.

Variable	Default value	Meaning
`CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES`	`12582912` (12 MiB)	Total size of all files copied into an execution
`CODE_INTERPRETER_MAX_WORKSPACE_FILES`	`20`	Maximum number of input files per execution
`CODE_INTERPRETER_MAX_ARCHIVE_FILES`	`30`	Maximum number of files copied back from the sandbox into the chat’s files after the execution
`CODE_INTERPRETER_MAX_OUTPUT_FILE_BYTES`	`10485760` (10 MiB)	Maximum size of a single result file, at most `67108864` (64 MiB)

Then apply the change in the installation directory. VARIOS AI is briefly unavailable while this runs.

docker compose up -d && docker compose exec php ./update.sh

Selection of input files

Before each execution, VARIOS AI collects the chat’s files and the files stored with the assistant. If two files have the same path, only the chat file is used. The files are sorted by the time of their last change, newest first, and taken over in this order:

Once CODE_INTERPRETER_MAX_WORKSPACE_FILES is reached, all further files are left out.
If a file no longer fits into the remaining volume of CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES, it is skipped. Smaller, older files can still be taken over afterwards.

Copying back the result files

After the execution, VARIOS AI copies all files from the sandbox’s working directory back. This includes the input files that were passed in: unchanged files do not create a new version, but they count toward CODE_INTERPRETER_MAX_ARCHIVE_FILES. Therefore, set this value higher than CODE_INTERPRETER_MAX_WORKSPACE_FILES. A result file larger than CODE_INTERPRETER_MAX_OUTPUT_FILE_BYTES is not saved and does not appear in the response. Regardless of this, at most 64 MiB in total are copied back per execution.

The input files are transferred to the code interpreter Base64-encoded, which makes them about one third larger. The following limits therefore also apply, and you set them in .env as well:

CODE_INTERPRETER_MAX_REQUEST_BYTES (default 20000000) limits the entire request including all input files.
CODE_INTERPRETER_MAX_WORKSPACE_FILE_B64_CHARS (default 18000000) limits a single input file to about 13.5 MB.
CODE_INTERPRETER_WORKSPACE_TMPFS_MB (default 128) limits the sandbox’s working directory, which must hold the input and result files together.

If you raise CODE_INTERPRETER_MAX_WORKSPACE_RAW_BYTES above about 14 MB, adjust these values accordingly. Otherwise, the code interpreter rejects the request and the execution fails.

Updates

Trigger updates under Administration → Settings → System Information. There you see whether a new version is available and choose the target version; the update helper varios.sh performs the update. Plan a maintenance window for this; VARIOS AI is unavailable for a few minutes during the update. Take a snapshot or backup before every update, see Backup and Restore.

Checks after installation

https://<PROJECT_DOMAIN> opens without a certificate warning.
Sign-in works with a regular account and with an administrator account; the Administration menu is visible.
License key entered, no license message.
A test chat is answered.
A test chat with the code interpreter works: “Use Python to calculate the first 20 prime numbers and save them as primes.txt.” The file appears in the chat.
The update helper runs as a systemd service, daily database backups appear under PostgresBackups.

Troubleshooting

Symptom	Check
Page does not load	DNS record, firewall, `docker compose ps`
Certificate warning in the browser	Ports 80 and 443 reachable from the internet, `ACME_EMAIL` set, `docker compose logs traefik`
Sign-in fails	Redirect URI in the identity provider, expired client secret, user’s role, `docker compose logs php`
Code interpreter does not respond	`docker compose logs code-interpreter code-interpreter-worker`; on `CODE_INTERPRETER_API_TOKEN must be set`, `must be at least 32 bytes` or `must not be identical`, check the tokens in `.env`, then `docker compose up -d`
Images are not downloaded	Registry login, `VERSION` in `.env`, internet access
Update aborts	AVX2 message in the log, `docker compose logs postgres`, then trigger the update again
Nothing runs after a reboot	`systemctl status docker`, `docker compose up -d`, status of the update helper

Getting Started

Usage

Administration

Installation

Operations

Security

Changelog

Installation Guide

Installation

Adjust code interpreter limits

Selection of input files

Copying back the result files

Updates

Checks after installation

Troubleshooting

​Installation

​Adjust code interpreter limits

​Selection of input files

​Copying back the result files

​Updates

​Checks after installation

​Troubleshooting

Installation

Adjust code interpreter limits

Selection of input files

Copying back the result files

Updates

Checks after installation

Troubleshooting