====== Installing the PWstudio GPU version on Rocky Linux 8.10 ======

Applies to: Rocky Linux 8.10\\
Includes: NVIDIA GPU driver, Docker, nvidia-container-toolkit

<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. System setup =====

==== 1.1 Disable the firewall ====

The first command stops the firewall immediately; the second prevents it from starting automatically at boot:

<code bash>
sudo systemctl stop firewalld
sudo systemctl disable firewalld
</code>

These two commands normally produce no output, or just a brief message — as long as there's no error in red, they succeeded.

===== 2. Install the NVIDIA GPU driver =====

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

<code bash>
# Install the hardware inspection tool
sudo dnf install pciutils -y

# Detect the GPU
lspci | grep -i nvidia
</code>

The first command installs a small tool called ''pciutils'' (which includes the ''lspci'' command). If it's already installed, this command will just say something like "already up to date" — that's normal and doesn't stop you from continuing. The second command is the actual GPU check:

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

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

<code bash>
nvidia-smi
</code>

If you see the GPU model, driver version, CUDA version (CUDA Version: 12.1 or later), etc., **the driver is already installed correctly**, and you can <wrap hi>skip straight to step 3, "Install Docker"</wrap> — skipping 2.3~2.7 entirely. If it says "command not found" (no driver version detected), the driver isn't installed yet, so continue with 2.3~2.7 below.

==== 2.3 Install dependencies ====

<code bash>
# Install the development tools group
sudo dnf groupinstall "Development Tools" -y

# Install development packages matching the current kernel
sudo dnf install -y kernel-devel-$(uname -r) kernel-headers

# Enable the necessary repository
sudo dnf install epel-release -y

# Install DKMS, which helps rebuild the driver automatically after kernel updates
sudo dnf install -y dkms
</code>

<wrap important>
The ''$(uname -r)'' in this command gets automatically substituted with your current kernel version — **you don't need to manually change it to anything else (e.g. your own username)**. Just copy and paste the entire line exactly as it is.
</wrap>

We recommend copying and pasting these four commands together as a block. Each one will scroll through some package installation output as it runs — that's normal, as long as it finishes without a red Error.

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

<code bash>
sudo grubby --args="nouveau.modeset=0 rd.driver.blacklist=nouveau" --update-kernel=ALL

# Reboot to apply the change
sudo reboot
</code>

<wrap important>
''sudo reboot'' immediately reboots the server — this is expected and necessary. Your terminal connection will drop after this — that's normal, don't worry. Wait 1-2 minutes for the server to finish rebooting, then **log back in to the server** (using MobaXterm or a similar tool), and continue with 2.5.
</wrap>

==== 2.5 Install the driver via the DNF package manager ====

<code bash>
# Enable the necessary repository
sudo dnf config-manager --set-enabled powertools

# Add the official NVIDIA repository
sudo tee /etc/yum.repos.d/cuda-rhel8.repo << 'EOF'
[cuda-rhel8-x86_64]
name=cuda-rhel8-x86_64
baseurl=https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64
enabled=1
gpgcheck=1
gpgkey=https://developer.download.nvidia.com/compute/cuda/repos/rhel8/x86_64/D42D0685.pub
EOF

# Enable the latest-dkms stream of the nvidia-driver module (DKMS is recommended)
sudo dnf module enable nvidia-driver:570-dkms -y

# Install the driver
sudo dnf install -y cuda-drivers
</code>

We recommend copying and pasting the ''sudo tee ... << 'EOF' ... EOF'' block **as a single whole** (from ''sudo tee'' all the way to the final ''EOF'') rather than running it piece by piece, since it's writing a multi-line configuration file. After running it, the screen will print this content back out exactly as it is — that's normal, not an error. The final command, ''dnf install -y cuda-drivers'', is what actually installs the driver; it downloads and installs quite a few packages, which may take a few minutes depending on your network speed — please be patient.

==== 2.6 Reboot the system ====

<code bash>
sudo reboot
</code>

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

==== 2.7 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 a table with the GPU model, driver version, CUDA version, etc., **the driver was installed successfully** — continue to the next step. If it still says "command not found," check whether the install process in 2.5 reported any errors.

----

===== 3. Install Docker =====

<WRAP tip>
If Docker is already installed on your machine (check with the command below — if you see a version number, it's already installed)
<code bash>
docker --version
</code>
you can skip this chapter and go straight to "4. Install nvidia-container-toolkit".
</WRAP>

==== 3.1 Install dependencies and add the official Docker repository ====

<code bash>
# Install dependency tools
sudo dnf install -y dnf-utils device-mapper-persistent-data lvm2

# Add the official Docker repository (using an Alibaba Cloud mirror for speed)
sudo dnf config-manager --add-repo \
  https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
</code>

The second command adds a Docker package repository hosted on Alibaba Cloud's mirror to your system, which makes downloading Docker faster and more reliable afterward (less likely to time out due to accessing servers outside mainland China).

==== 3.2 Install the Docker engine ====

<code bash>
sudo dnf install -y docker-ce docker-ce-cli containerd.io
</code>

This installs Docker itself; it may take a minute or two depending on your network speed, and you'll see a lot of package information scroll by — that's normal.

<wrap tip>
If this step fails with a conflict involving podman (Rocky/CentOS 8 systems sometimes come with podman pre-installed), see [[en:pwstudio:qa:q102|q102: Docker install error on Rocky 8.10]] for the fix.
</wrap>

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

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

The first command starts the Docker service, the second sets it to start automatically at boot; these usually produce no output, or just a brief message — that's normal.

==== 3.4 Verify the installation ====

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

**If you see text starting with "Hello from Docker!"**, Docker was installed successfully.

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

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

<wrap important>
''$USER'' is a system variable that automatically gets substituted with your current login username — **no manual editing needed**, 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, ''exit'' first and then log back in to the server.

----

===== 4. Install nvidia-container-toolkit =====

This step lets the Docker container use the NVIDIA GPU on the host machine.

<wrap tip>If you're installing the PWstudio CPU version, please go back to the previous page.</wrap>

==== 4.1 Install nvidia-container-toolkit ====

<code bash>
sudo dnf install -y nvidia-container-toolkit
</code>

==== 4.2 Configure the Docker runtime ====

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

==== 4.3 Restart the Docker service ====

<code bash>
# Be sure to restart the Docker service for the configuration to take effect
sudo systemctl restart docker
</code>

<wrap tip>
Steps 4.2 and 4.3 only need to be run once — you don't need to redo them every time you use Docker; once configured, they stay in effect.
</wrap>

==== 4.4 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 (GPU model, driver version, etc.), nvidia-container-toolkit was installed successfully and the container can now use the GPU.

===== 5. Install the PWstudio GPU version =====

Once all three pieces of base environment are installed, click the link to continue installing PWstudio itself, 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~~