Manual Installation

Eight steps to install GPU Shards OS on Ubuntu by hand. Prefer the fast path? Just run the one-line installer — it does all of this for you.

Assumes an Ubuntu 22.04+ host with an NVIDIA driver already installed. Verify the GPU is visible with nvidia-smi before you start.

1. Install Docker Engine

Add Docker's APT repo and install the Engine, CLI, containerd, and the Compose plugin. Add your user to the docker group so you don't need sudo for every command.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"   # log out / in for this to take effect

2. Install the NVIDIA Container Toolkit

Required so Docker containers can access the GPU. Assumes the NVIDIA driver is already installed on the host (verify with nvidia-smi).

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -fsSL 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

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Sanity check — should print the GPU table
docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubuntu22.04 nvidia-smi

3. Install Python 3 and Node.js 20

The backend is FastAPI (Python 3.10+) and the frontend is Next.js 16 (Node 20+).

sudo apt-get install -y python3 python3-venv python3-pip

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

node -v && python3 --version

4. Get the project source

Clone the repository from GitHub.

git clone https://github.com/penkow/gpu-shards-os.git
cd gpu-shards-os

5. Create a Python venv and install backend deps

Isolate the backend dependencies in a virtualenv so they don't collide with the system Python.

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip wheel
pip install -r requirements.txt

6. Install frontend deps and build

Install the Next.js dependencies and produce a production bundle. You can skip the build during development and use npm run dev instead.

cd frontend
npm install
npm run build
cd ..

7. Build the HAMi libvgpu image

Builds hami-core-demo:latest — the slim CUDA image with libvgpu.so from Project-HAMi baked in at /libvgpu/build/libvgpu.so. This is the default image used when you deploy a container from the panel.

docker build -t hami-core-demo:latest -f Dockerfile .

# Quick sanity test — the cap should report 4096 MiB, not the real card size:
docker run --rm --gpus all \
  -e LD_PRELOAD=/libvgpu/build/libvgpu.so \
  -e CUDA_DEVICE_MEMORY_LIMIT=4096m \
  hami-core-demo:latest nvidia-smi

8. Launch the stack

run.sh starts the FastAPI backend on :8000 and the Next.js frontend on :3000, and tears both down on Ctrl-C.

source .venv/bin/activate
./run.sh

# Then open the panel:
#   http://localhost:3000

Done. Open http://localhost:3000 and deploy your first container — see the Quick Start.