====== Installing the PWstudio GPU version on Ubuntu 24.04 ======

Applies to: Ubuntu 24.04 LTS\\
Includes: The PWstudio GPU version is like any other mainstream container-based GPU application — at runtime it depends on the NVIDIA GPU driver, Docker, and nvidia-container-toolkit. Before installing the PWstudio GPU version, please make sure these dependencies are already installed on your machine. This guide includes installation steps for each of them for reference.

<wrap important>
Before you start, we strongly recommend reading [[en:pwstudio:readme|Read this before installing PWstudio]] first, especially the notes about "copy-paste" and "the command prompt is not part of the command." If you don't yet know how to use a tool to log in to a server or upload/download files, read [[en:pwstudio:mobaxterm|the MobaXterm beginner tutorial]] first.
</wrap>

----

===== 1. Install the NVIDIA GPU driver =====

<wrap tip>
If your machine already had the driver installed, do the check in 1.2 first — if there's output, you can skip this entire chapter 1 and go straight to "2. Install Docker".
</wrap>

==== 1.1 Confirm the system can detect the NVIDIA GPU ====

<code bash>
lspci | grep -i nvidia
</code>

  * **There's output** (a line containing "NVIDIA"): the GPU was detected — continue on.
  * **No output**: the GPU wasn't detected. Contact your administrator to confirm the hardware before continuing with the driver install.

==== 1.2 Check whether the driver is already installed ====

<code bash>
nvidia-smi
</code>

If you see the GPU model, driver version, CUDA version, etc., the driver is already installed, <color blue>skip this step</color>. That means you can skip 1.3~1.7 entirely and go straight to chapter 2, "Install Docker". If it says "command not found," it isn't installed yet — continue with the steps below.

==== 1.3 Disable the built-in nouveau driver ====

<code bash>
# 1. Disable nouveau first
sudo bash -c "echo blacklist nouveau > /etc/modprobe.d/blacklist-nvidia-nouveau.conf"
sudo bash -c "echo options nouveau modeset=0 >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf"
sudo update-initramfs -u

# 2. Reboot the system (so disabling nouveau takes effect)
sudo reboot
</code>

<wrap important>
After running ''sudo reboot'', the terminal connection will drop — this is expected and necessary, don't worry. Wait 1-2 minutes for the server to finish rebooting, then **log back in to the server** (e.g. reconnect with MobaXterm), and continue with step 1.4 below.
</wrap>

==== 1.4 Update package sources ====

<code bash>
sudo apt update
</code>

This refreshes the package source list. You'll see the check status for each source scroll by — that's normal, just let it finish; no further action needed.

==== 1.5 Install the required tool ====

<code bash>
sudo apt install -y ubuntu-drivers-common
</code>

==== 1.6 Install the specified driver version ====

<code bash>
# Install driver version 535 (supports CUDA 12.1 and above)
sudo ubuntu-drivers install nvidia:535
</code>

> To see what driver version the system recommends, you can first run ''sudo ubuntu-drivers list'' for reference.

This step downloads and installs the driver, which may take a few minutes depending on your network speed — please be patient and don't force-close the terminal partway through.

==== 1.7 Reboot the system ====

<code bash>
sudo reboot
</code>

Again, the terminal will disconnect after this — that's normal. Wait 1-2 minutes, then log back in to the server.

==== 1.8 Verify the driver installation ====

<code bash>
nvidia-smi
</code>

<wrap important>
Note that ''nvidia-smi'' has a hyphen in the middle and no space — we recommend copying and pasting it directly rather than typing it manually.
</wrap>

If you see the GPU model, driver version, CUDA version, etc., **the driver was installed successfully (as shown in the example below — a table like this means it worked)**:

NVIDIA-SMI 535.309.01 is the version number of the command-line tool itself — the executable used to query the GPU's status;

Driver Version: 535.309.01 is the version of the NVIDIA GPU kernel driver — the core low-level program that actually controls the GPU hardware and talks to the OS kernel;

CUDA Version: 12.2 is the highest CUDA runtime version this driver can support. As long as the CUDA version required by a CUDA application (such as PyTorch or TensorFlow) is 12.2 or lower, it can use the GPU normally.

{{:pwstudio:nvidia-smi.png?400|}}
----

===== 2. Install Docker =====

Before installing, please check whether Docker is already installed on your machine:

<code bash>
docker --version
# If it prints something like "Docker version 29.6.1, build 8900f1d", Docker is already installed — you can skip this chapter and go straight to "3. Install nvidia-container-toolkit"

systemctl status docker
# Check whether the Docker service is running — if it shows "active (running)", it's not only installed but also running
</code>
==== 2.1 Install the required dependencies ====

<code bash>
sudo apt update
sudo apt install -y ca-certificates curl
</code>

==== 2.2 Add Docker's official GPG key and package source (using a mirror inside mainland China) ====

<code bash>
# 1. Create the directory to hold the key
sudo install -m 0755 -d /etc/apt/keyrings

# 2. Download and save Docker's GPG key from the Alibaba Cloud mirror
sudo curl -fsSL http://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 3. Add the Docker package source (also via the Alibaba Cloud mirror)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] http://mirrors.aliyun.com/docker-ce/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
</code>

<wrap tip>
We recommend copying and pasting all of step 3 (from ''echo'' to the final ''> /dev/null'') **as one whole block** rather than running it line by line, since it's really a single command that spans multiple lines. Here, ''$(dpkg --print-architecture)'' and ''$(. /etc/os-release && echo ...)'' are both system variables that get automatically substituted with your system's architecture and version codename — **no manual editing needed**.
</wrap>

==== 2.3 Install Docker ====

<code bash>
# Refresh the package index again
sudo apt update

# Install Docker and its components
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
</code>

This downloads and installs Docker and its related components, which may take a minute or two depending on your network speed.

==== 2.4 Start Docker and enable it at boot ====

<code bash>
sudo systemctl start docker
sudo systemctl enable docker
</code>

==== 2.5 Verify the installation ====

<code bash>
sudo docker run --rm swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/hello-world:latest

# Seeing output like the following means the install succeeded
# Hello from Docker!
# This message shows that your installation appears to be working correctly.

# To generate this message, Docker took the following steps:
#  1. The Docker client contacted the Docker daemon.
#  2. The Docker daemon pulled the "hello-world" image from the Docker Hub. (amd64)
#  3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
#  4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.

#  To try something more ambitious, you can run an Ubuntu container with:
#   $ docker run -it ubuntu bash

</code>

**As long as you see the words "Hello from Docker!" in the terminal, Docker was installed successfully and is working correctly** — you can move on to the next step with confidence.

==== 2.6 (Optional) Allow a non-root user to run Docker ====

<code bash>
sudo usermod -aG docker $USER
</code>

<wrap important>
''$USER'' here is a system variable that gets automatically substituted with your currently logged-in username — **you don't need to manually change it to your own username**, just copy and paste it as-is.
</wrap>

> Note: you need to log out and back in (or restart your session) for this to take effect. That is, after running this command, exit the terminal (type ''exit'') and log back in to the server for the setting to actually apply.

----

===== 3. Install nvidia-container-toolkit =====

> For Ubuntu 24.04, we recommend installing via NVIDIA's official apt repository, rather than the now-deprecated ''apt-key add'' method.

==== 3.1 Download the offline package and upload it to the server ====

> Link: http://223.70.160.60:9999/qflow/nvidia-container-toolkit_1.19.1_deb_amd64.tgz
> Username: pwmat
> Password: SimplyTheBest

You can also download it directly on the server (if your server has direct access to the outside internet, you can skip the "download in browser, then upload" step and run the command below directly in the server's terminal):
<code bash>
wget --user=pwmat --password=SimplyTheBest "http://223.70.160.60:9999/qflow/nvidia-container-toolkit_1.19.1_amd64.deb.tgz"
</code>

If your server doesn't have direct outside internet access, do it the same way as the driver and Docker earlier: download it in a browser first, then upload it to the server with MobaXterm.

==== 3.2 Install nvidia-container-toolkit ====

<code bash>
tar -zxvf nvidia-container-toolkit_1.19.1_deb_amd64.tgz
cd nvidia-container-toolkit_1.19.1_deb_amd64
sudo dpkg -i *.deb
</code>

The first command extracts the archive, the second enters the extracted folder, and the third installs every ''.deb'' package inside it.

==== 3.3 Configure the Docker runtime ====

<code bash>
sudo nvidia-ctk runtime configure --runtime=docker
</code>

==== 3.4 Restart the Docker service ====

<code bash>
sudo systemctl restart docker
</code>

<wrap tip>
Steps 3.3 and 3.4 only need to be run once — once configured, they stay in effect, so you don't need to redo them every time before using Docker.
</wrap>

==== 3.5 Verify the installation ====

<code bash>
sudo docker run --rm --gpus all swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
</code>

If ''nvidia-smi'' inside the container produces normal output (as shown below — the GPU model, driver version, etc.), nvidia-container-toolkit was installed successfully and the container can now use the GPU.
{{:pwstudio:docker-install-check.png?400|}}
===== 4. Install the PWstudio GPU version =====

Click the link below, starting from "Install the server.py service on the host machine": [[en:pwstudio:quickstart_gpu#Install the server.py service on the host machine|Go to "Install the server.py service on the host machine"]], and follow the guide through to the end.

~~DISCUSSION:off~~