Debian 12 (Bookworm) Setup Guide¶

logo

Overview¶

Debian 12 (Bookworm) is Juno's preferred distribution for on-premises installations due to its stability, reliability, and straightforward setup process.

Base Node Configuration¶

System Updates¶

First, ensure your system is fully up to date:

sudo apt update
sudo apt upgrade -y

Swap Configuration¶

Disable swap for optimal Kubernetes performance:

sudo swapoff -a

To make this change persistent across reboots, comment out any swap entries in /etc/fstab:

sudo sed -i '/swap/s/^/# /' /etc/fstab

Docker Installation¶

Docker installation includes containerd and other necessary packages for Kubernetes, with pre-configured container runtimes:

sudo apt install curl -y
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Enable Docker to start on boot:

sudo systemctl enable docker

Recommended Packages¶

These additional packages support various storage backends and enhance functionality:

sudo apt install open-iscsi nfs-common -y

GPU Configuration¶

Follow these steps to prepare your system for GPU-enabled workstations and rendering nodes.

Update System for GPU Support¶

Ensure your system is fully up to date:

sudo apt update
sudo apt upgrade -y

Verify GPU Hardware Detection¶

Verify that your GPU hardware is properly recognized:

ls -la /dev/ | grep dri

Video Device Mounted

If this passes, you should see the following output:

drwxr-xr-x  3 root root          80 Jan 30 14:03 dri

No Output

If you do not see this output, the kernel is not recognizing the GPU. Normally this is due to the kernel not having the correct firmware or the kernel needs to be updated. Please refer to the Debian Wiki for more information.

NVIDIA Driver Installation¶

To install the NVIDIA drivers, follow these steps. You can also reference the Debian NVIDIA Wiki directly.

1. Enable Non-Free Repositories¶

First, enable the necessary repositories for NVIDIA drivers:

sudo su
echo "deb http://deb.debian.org/debian/ bookworm main contrib non-free non-free-firmware" >> /etc/apt/sources.list

Target Translations

If you get the following error:

W: Target Translations (non-free-firmware/i18n/Translation-en) is configured multiple times in /etc/apt/sources.list:1 and /etc/apt/sources.list:12

Remove the deb http://deb.debian.org/debian/ bookworm main non-free-firmware duplicate entry from the /etc/apt/sources.list file.

2. Install NVIDIA Drivers¶

Install the NVIDIA drivers and required dependencies:

sudo apt update
sudo apt install -y nvidia-driver firmware-misc-nonfree linux-headers-$(uname -r)
sudo reboot

3. Verify Driver Installation¶

After the system restarts, verify that the drivers are installed correctly:

nvidia-smi

Drivers Installed

If this passes, you should see the following output but for your GPU model:

+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.216.01             Driver Version: 535.216.01   CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA GeForce RTX 2080        On  | 00000000:00:10.0 Off |                  N/A |
|  0%   33C    P8              13W / 215W |      1MiB /  8192MiB |      0%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|  No running processes found                                                           |
+---------------------------------------------------------------------------------------+

Confirm GPU device mounting:

ls -la /dev/dri/

Video Device Mounted Properly With NVIDIA Drivers

If this passes, you should see something similar to the following output with your cards and a render device:

total 0
drwxr-xr-x  3 root root        120 Jan 30 18:12 .
drwxr-xr-x 18 root root       3.4K Jan 30 18:13 ..
drwxr-xr-x  2 root root        100 Jan 30 18:12 by-path
crw-rw----  1 root video  226,   0 Jan 30 18:12 card0
crw-rw----  1 root video  226,   1 Jan 30 18:12 card1
crw-rw----  1 root render 226, 128 Jan 30 18:12 renderD128

NVIDIA Container Toolkit Installation¶

Set up the NVIDIA Container Toolkit to enable GPU access for containers. This will allow us to run GPU enabled containers which is then provided as a runtime in kubernetes via the CRI.

1. Add NVIDIA Container Toolkit Repository¶

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

2. Install NVIDIA Container Toolkit¶

sudo apt update
sudo apt install -y nvidia-container-toolkit

3. Configure Runtime Environments¶

For containerd (required for Kubernetes):

sudo nvidia-ctk runtime configure --runtime=containerd
sudo systemctl restart containerd

If Docker is installed:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

4. Verify Container Toolkit Installation (Optional)¶

To confirm the NVIDIA Container Toolkit is working correctly:

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Testing the NVIDIA Container Toolkit

If you would like to test the NVIDIA Container Toolkit, you can run the following commands. This is not needed for the installation but is a good way to verify that the toolkit is installed correctly.

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Working Toolkit

If you see the output of nvidia-smi then the toolkit is installed correctly.

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
INFO[0000] Loading config from /etc/docker/daemon.json
INFO[0000] Wrote updated config to /etc/docker/daemon.json
INFO[0000] It is recommended that docker daemon be restarted.
Unable to find image 'ubuntu:latest' locally
latest: Pulling from library/ubuntu
de44b265507a: Pull complete
Digest: sha256:80dd3c3b9c6cecb9f1667e9290b3bc61b78c2678c02cbdae5f0fea92cc6734ab
Status: Downloaded newer image for ubuntu:latest
Thu Jan 30 23:44:20 2025
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.216.01             Driver Version: 535.216.01   CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA GeForce RTX 2080        On  | 00000000:00:10.0 Off |                  N/A |
|  0%   30C    P8              12W / 215W |      1MiB /  8192MiB |      0%      Default |
|                                         |                      |                  N/A |
+-----------------------------------------+----------------------+----------------------+

+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|  No running processes found                                                           |
+---------------------------------------------------------------------------------------+

Next Steps¶

After completing this setup, Proceed to Orion cluster deployment by following our On-Prem Installation Guide.

For further assistance, contact Juno Support.