Purpose
This article explains how to install Giotto on your infrastructure, including the required access credentials, the installation flow for the head node, and the optional installation flow for worker nodes.
Important: after the installation, make sure to restrict the public network access with firewall rules (see Restrict Public Network Access With Firewall Rules)
Overview
The installation of Giotto starts with access to the deployment bundle. Once you receive the required credentials and version information, the bundle can be downloaded and installed on the target machines.
A standard installation usually follows this order:
- contact the Giotto.ai business team
- receive the deployment credentials and target version
- prepare the head node and verify prerequisites
- install Giotto on the head node
- optionally install Giotto on worker nodes
The head node is the main starting point of the installation. Worker nodes are optional and are only needed when the deployment includes a multi-node setup.
Before you begin
Before installing Giotto, make sure you have:
- a target VM or node for the head node
- optional additional VMs or nodes for worker nodes
- access to the shell on those machines
- permission to run commands with
sudo - the installation prerequisites for:
- NVIDIA / CUDA and NVIDIA Container Toolkit if GPU workloads are needed
- Docker and Docker Compose
If the prerequisites are not already installed, the installation script will attempt to install them automatically. Even so, it is recommended to validate them in advance on the target machines.
Step 1 — Contact the business team
To begin the installation process, contact the Giotto.ai business team at:
business@giotto.ai
They will provide the information needed to retrieve the deployment bundle.
Step 2 — Receive your deployment credentials
After contacting the business team, you will receive:
- a deployment user
- a deployment token
- the target version to install
- the GCS base 64 read-only credentials
These values are required to authenticate against the package registry and download the Giotto bundle.
In the installation commands below, these values are represented as:
DEPLOY_USERDEPLOY_TOKENVERSION
and in the install.env file as
GCS_CREDENTIALS_B64
Step 3 — Prepare the head node
Before installing Giotto on the head node, make sure that:
- the machine is reachable
- Docker is installed and working: see the docker setup guide
- if GPUs are required, CUDA, NVIDIA drivers, and NVIDIA Container Toolkit are installed: see the CUDA setup guide
- Secure the Giotto VM with firewall rules: see the firewall setup guide
If these prerequisites are missing, the installer will try to install them automatically. However, it is still recommended to validate them before starting the platform installation.
Furthermore, one needs to prepare the install.env file, where secrets and special parameters are specified. This is the minimum configuration required to successfully install Giotto:
PUBLIC_HOSTNAME=stage.giotto.ai # your subdomain where to deploy Giotto
PUBLIC_BASE_URL=https://stage.giotto.ai
RAY_HEAD_IP=192.168.0.35 # private internal IP of the VM hosting Giotto
RAY_NODE_IP=192.168.0.21 # private internal IP of the worker node (only for multi-node deployment)
SSH_HOST=89.169.121.110 # public IP of the VM hosting Giotto
SSH_USER=m_caorsi # optional, ssh user
SSH_PRIVATE_KEY_B64="LS0tLS1...LS0tLS0K" # optional, base64 encoding of the private ssh key
HF_TOKEN=hf_BxM...UQnO # optional, hugginface token
OPENAI_API_KEY="" # optional, OpenAI token
GCS_CREDENTIALS_B64=<my_gcs_credentials_b64> # from giotto team
KEYCLOAK_ENTRA_ALIAS=entra-id # optional, external identity provider: leave it as is if not used
KEYCLOAK_ENTRA_TENANT_ID=0bb0e6...c73c3 # optional, external identity provider tenant ID
KEYCLOAK_ENTRA_CLIENT_ID=ad7020...521 # optional, external identity provider client ID
KEYCLOAK_ENTRA_CLIENT_SECRET=Hks...acx # optional, external identity provider secret
KEYCLOAK_ENTRA_USE_BROKER=true
# optional, SMTP works but it is considered an legacy system. You can configure it like so:
EMAIL_BACKEND=smpt
SMTP_HOST=smtp.gmail.com # mail server
SMTP_PORT=587 # port for smtp in your mail server
SMTP_USER=alerting.system123@gmail.com # username of the email sending alerts
SMTP_PASSWORD=zij...f # password for the email account
SMTP_FROM_ADDRESS=alerting.system123@gmail.com # email sending alerts
SMTP_FROM_NAME="Platform Alerts"
SMTP_STARTTLS=true
SMTP_SSL=false
SUPERSET_ALERT_EMAIL_TO=m.caorsi@giotto.ai # address receiving of the alerts
# optional, Alternatively you can use MS Graph, which you configure like so:
EMAIL_BACKEND=microsoft_graph
GRAPH_TENANT_ID=0bb...73c3
GRAPH_CLIENT_ID=20...245
GRAPH_CLIENT_SECRET=...
GRAPH_MAILBOX=model@giotto.ai
# NOT OPTIONAL, you must set these based on the number of GPUs
RAY_SERVE_MIN_REPLICAS=1
RAY_SERVE_MAX_REPLICAS=1
RAY_SERVE_NUM_REPLICAS=1
# NOT OPTIONAL, Leave these as is, unless you want to connect your stripe account (for API payment)
STRIPE_SECRET_KEY=a
STRIPE_WEBHOOK_SECRET=aYou need to place this install.env file in the same folder from where you will be running the installation script (ref. the next section). Make sure to change the values of the variables RAY_HEAD_IP and RAY_NODE_IP to match your head node ip and worker node ip respectively.
To enable GCS integration, you must provide a base64-encoded string of your credentials in the install.env file. You can generate the value for GCS_CREDENTIALS_B64 by running the following command on your JSON key file:
base64 -i credential_file.jsonFinally, you also need to prepare the HTTPS certificates (both the bundle and the key). You need to store them inside a folder called ./certs in the same folder from where you will be running the installation script (ref. the next section).
Relevant prerequisite articles:
- Prerequisite: Install CUDA, NVIDIA Drivers, and NVIDIA Container Toolkit
- Prerequisite: Install Docker and Docker Compose
Step 4 — Install Giotto on the head node
Run the following commands on the head node.
Replace the placeholder values with the credentials and version you received from the business team.
export DEPLOY_USER="<DEPLOY_USER>"
export DEPLOY_TOKEN="<DEPLOY_TOKEN>"
export VERSION="<VERSION>"
sudo mkdir -p /opt/giotto
sudo cp -r "./certs" "/opt/giotto"
sudo cp "./install.env" "/opt/giotto"
mkdir -p /tmp/gexpert
cd /tmp/gexpert
curl --fail-with-body --location \
--user "${DEPLOY_USER}:${DEPLOY_TOKEN}" \
--output bundle.tar.gz \
"https://gitlab.com/api/v4/projects/79910854/packages/generic/giotto-bundle/${VERSION}/giotto-bundle-${VERSION}.tar.gz"
sudo tar -xzf bundle.tar.gz -C /opt/giotto
cd /opt/giotto
sudo bash scripts/install_bundle.sh \
--role head \
--version "${VERSION}" \
--deploy-user "${DEPLOY_USER}" \
--deploy-token "${DEPLOY_TOKEN}"
What this does
This command sequence performs the following actions:
- exports the deployment variables into the shell
- creates a temporary working directory
- downloads the giotto bundle from the package registry
- extracts the bundle into
/opt/giotto - runs the installation script in head node mode
The --role head argument is what tells the installer that this machine is the head node of the deployment.
Step 5 — Optionally install Giotto on worker nodes
If your deployment uses worker nodes, repeat the installation flow on each worker node using the worker variant of the script. You still need to have CUDA, Docker and the install.env file ready.
Run the following commands on each worker node:
export DEPLOY_USER="<DEPLOY_USER>"
export DEPLOY_TOKEN="<DEPLOY_TOKEN>"
export VERSION="<VERSION>"
sudo mkdir -p /opt/giotto
sudo cp "./install.env" "/opt/giotto"
mkdir -p /tmp/gexpert
cd /tmp/gexpert
curl --fail-with-body --location \
--user "${DEPLOY_USER}:${DEPLOY_TOKEN}" \
--output bundle.tar.gz \
"https://gitlab.com/api/v4/projects/79910854/packages/generic/giotto-bundle/${VERSION}/giotto-bundle-${VERSION}.tar.gz"
sudo tar -xzf bundle.tar.gz -C /opt/giotto
cd /opt/giotto
sudo bash scripts/install_bundle.sh \
--role worker \
--version "${VERSION}" \
--deploy-user "${DEPLOY_USER}" \
--deploy-token "${DEPLOY_TOKEN}"What changes on worker nodes
The process is almost identical to the head node installation. The main difference is the installer role:
--role worker
This tells the installer that the current machine should be set up as a worker node rather than as the cluster head.
Understanding the main installation variables
DEPLOY_USER
The username provided by Giotto.ai for accessing the deployment package.
DEPLOY_TOKEN
The token provided by Giotto.ai for authenticating the package download.
VERSION
The version of the Giotto bundle to install.
This value is provided by the business team and should match the intended release.
Installation paths used by the script
The installation flow uses two key filesystem locations:
Temporary download path
/tmp/gexpert
This is used to download the compressed bundle.
Final installation path
/opt/Giotto
This is the target directory where the bundle is extracted and from which the installer is run.
What happens during installation
The install_bundle.sh script performs the installation logic based on the selected role.
Depending on the environment and what is already installed, it may:
- validate or install prerequisites
- prepare the local machine for Giotto services
- configure the node according to the chosen role
- install the software bundle components
Because of this, the installer should be run with the correct role and with valid deployment credentials.
How to validate that installation completed
After installation, validate the setup by checking:
- whether the installer completed successfully
- whether Docker is running
- whether expected services or files are present under
/opt/giotto - whether the head node and optional worker nodes are configured consistently
If your environment includes GPUs, also confirm that the GPU stack is still healthy after installation.
Common issues
The bundle download fails
This usually means that:
-
DEPLOY_USERorDEPLOY_TOKENis incorrect -
VERSIONis incorrect - the package is not available for the given version
- outbound connectivity to the package registry is blocked
The installation script fails on prerequisites
This may happen if Docker or CUDA-related dependencies are missing or if the environment does not match the expected OS/runtime assumptions.
The head node installs correctly but workers fail
In this case, verify:
- the same credentials are being used
- the same version is being installed
- the worker script uses
--role worker - networking and VM access are working correctly on the worker nodes
Permissions errors occur during extraction or installation
Make sure the commands are run with the expected privileges and that sudo is available.
Best practices
Install the head node first
Always start with the head node. Worker nodes should only be installed after the head node installation path is clear.
Keep the version consistent across nodes
In multi-node deployments, all nodes should use the same bundle version.
Validate prerequisites before running the installer
Even though the script may try to install missing dependencies, it is better to know the state of the machine in advance.
Keep the credentials secure
The deployment user and token provide access to the installation package and should be handled as sensitive credentials.
Save the exact version used
Record the installed version for future upgrades, debugging, or reproduction of the deployment.
Summary
The installation flow for Giotto is:
- contact business@giotto.ai
- receive the deployment user, token, and version
- prepare the head node and validate prerequisites
- run the head-node installation script
- optionally repeat the process on worker nodes using the worker role
This gives you the base platform installation on which the rest of the Giotto workflows can run.
Comments
0 comments
Article is closed for comments.