> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Guide

> Install, configure and update VARIOS AI on your own Linux server with Docker

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](/en/monthly/operations/system-requirements) beforehand.

<Info>
  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.
</Info>

## Installation

<Steps>
  <Step title="Prepare the server">
    Install the current updates of your distribution, enable time synchronization and set up the firewall according to the [system requirements](/en/monthly/operations/system-requirements#network-and-domain). A correct clock is mandatory for sign-in and certificates.

    ```bash theme={null}
    sudo timedatectl set-ntp true
    ```
  </Step>

  <Step title="Install Docker">
    Install Docker Engine and Docker Compose v2 following your distribution's instructions or with the official script, and enable autostart.

    ```bash theme={null}
    curl -fsSL https://get.docker.com -o get-docker.sh
    sudo sh get-docker.sh
    sudo systemctl enable --now docker
    docker compose version
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    sudo mkdir -p /docker/variosai
    cd /docker/variosai
    chmod +x varios.sh
    ```
  </Step>

  <Step title="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                                                                                       |
    | `OIDC_*`                                                                   | Credentials of your identity provider, see [Setting up Microsoft Entra ID](/en/monthly/installation/microsoft-entra-id) |
    | `ADMIN_GROUP_NAME`, `SUPERADMIN_GROUP_NAME`, `COMPLIANCE_ADMIN_GROUP_NAME` | Names of the roles in the identity provider that administrators receive                                                 |
    | `SCIM_*`                                                                   | User synchronization, see the Entra page                                                                                |

    <Warning>
      The `.env` contains passwords and secrets. Do not share it and include it in every backup.
    </Warning>
  </Step>

  <Step title="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](/en/monthly/security/traefik-certificates). For a reverse proxy of your company in front of VARIOS AI, please contact support.
  </Step>

  <Step title="Log in to the container registry">
    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.

    ```bash theme={null}
    docker login aibroker.azurecr.io
    ```
  </Step>

  <Step title="Start the services">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Set up the database">
    ```bash theme={null}
    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.

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

  <Step title="Sign in and enter the license">
    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](/en/monthly/admin/settings/system-information).
  </Step>

  <Step title="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](/en/monthly/security/systemd-service).

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

## Updates

Trigger updates under Administration → Settings → [System Information](/en/monthly/admin/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](/en/monthly/operations/backup).

## 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.
* 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` |
| 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                       |