📋 Prerequisites

Please read carefully as there can be many points of failure when installing/deploying everything into a clean environment.

🖥️ OS Requirements

Please note that the OSes mentioned below are the versions we support, whatever is not listed here is not supported, and we will not provide support for.

Linux OS (Ubuntu 24.04 LTS +, Debian 10+ are preffered, RHEL 9+).
Windows 11+/Windows Server 2022+ (Requires WSL 2.0 installation and the installation of an Ubuntu image, for a working setup, follow this guide to get going, and get back here when things are working).
macOS 15+ (Sequoia).

🧰 Software requirements (Linux/macOS)

Software required on machine (the minimum/basics to get demos running):

make
git + git-lfs
Docker
python3.11

🔐 Other requirements (User Permissions/Firewall)

- a Linux account with 'admin' rights, if possible, if not, you will need to get your IT team to take a look at this README and install the packages for you using the steps below (make sure they look at [Docker rootless installation steps](https://docs.docker.com/engine/security/rootless))
- firewall whitelisting of the following addreses:
    - https://github.com/
    - https://hub.docker.com/
    - https://docker.io 
    - http://download.docker.com 
    - https://huggingface.co/
    - https://www.nltk.org
    - https://pypi.org/
    - https://pypi.python.org  
    - https://Files.pythonhosted.org 
    - https://pythonhosted.org

⚙️ Installation steps

Assuming you are the system admin, meaning you haveSUDO rights. You can use the script with SUDO rights, located at /scripts/installation_utils/install_docker_and_utils.sh, it can be used on Debian(10+)/Ubuntu(22.04+)/RedHAT RHEL 8/9 only, run it once and everything should be set up.

Execute the following commands in the root directory of the repo:

git-lfs pull
(OPTIONAL, if you already have the software in this section installed)sudo bash ./scripts/installation_utils/install_docker_and_utils.sh , and wait for it to finish, it may take a while to get all the packages..
cd deploy
make git-update-submodules
check that docker works correctly : docker pull hello-world
if no errors, run: docker run --rm hello-world, it should run without issues
if there are any issues check the below warning section

Warning

IMPORTANT NOTE: Do a git-lfs pull so that you have everything downloaded from the repo (including bigger zipped files.).

Warning

Ensure all Git submodules are initialized and updated: make git-update-submodules

Warning

Consult the if there are issues with the docker setup. If Docker fails to install or docker pull hello-world does not work:

- Follow the official [Docker installation steps](https://docs.docker.com/engine/install/debian/)
- Ensure your user is in the docker group
- For non-sudo users, check Docker rootless mode and required post-install steps:
    - https://docs.docker.com/engine/security/rootless/
    - https://docs.docker.com/engine/install/linux-postinstall/

⚠️ Essential Elasticsearch Requirement

Warning

Elasticsearch may fail to start unless vm.max_map_count is increased.

If this value is too low, Elasticsearch will exit with the error:

```bash
bootstrap checks failed
max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
```

If you did not run the installation script, set it manually:

Temporary (until reboot): bash sudo sysctl -w vm.max_map_count=262144

Permanent (persists across reboots): Add the line below to /etc/sysctl.conf:

```bash
vm.max_map_count=262144
```

Or a one-liner:

```bash
sudo sh -c "echo 'vm.max_map_count=262144' >> /etc/sysctl.conf"
```

Then apply:

```bash
sudo sysctl -p
```

The install_docker_and_utils.sh script automatically configures this. You only need to set it manually if the script was skipped.

🏅 Deploying services

If everything up to this point is running fine, then, congratulations, you should now be able to start looking at the deployment section