Skip to content

Docker & Podman Deployment

Run Bazzite Pods on any platform with Docker or Podman.

Prerequisites

Docker

Podman

NVIDIA GPU (Optional)

For GPU support on Linux, install NVIDIA Container Toolkit:

# Ubuntu/Debian
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
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Fedora/RHEL
sudo dnf install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Quick Start

# NVIDIA GPU
docker run -it --rm --gpus all -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable

# CPU-only (macOS/Windows/Linux without GPU)
docker run -it --rm -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable

# AMD/Intel GPU (Linux)
docker run -it --rm --device=/dev/dri -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable

Pod Examples

nvidia-python (ML/AI)

# Interactive shell
docker run -it --rm --gpus all -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable

# Run training script
docker run --rm --gpus all -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-nvidia-python:stable \
  pixi run --manifest-path /opt/pixi/pixi.toml python /workspace/train.py

jupyter (JupyterLab)

# Start JupyterLab (access http://localhost:8888)
docker run -it --rm --gpus all -p 8888:8888 -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-jupyter:stable

# Different port
docker run -it --rm --gpus all -p 9999:8888 -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-jupyter:stable

devops (Cloud Tools)

# With credentials
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.aws:/home/jovian/.aws:ro \
  -v ~/.kube:/home/jovian/.kube:ro \
  ghcr.io/atrawog/bazzite-ai-pod-devops:stable

# With environment variables
docker run -it --rm \
  -e AWS_ACCESS_KEY_ID=xxx \
  -e AWS_SECRET_ACCESS_KEY=xxx \
  -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-devops:stable

playwright (Browser Automation)

# With VNC access (connect to localhost:5900)
docker run -it --rm -p 5900:5900 -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-playwright:stable

# Run headless tests
docker run --rm -v $(pwd):/workspace \
  ghcr.io/atrawog/bazzite-ai-pod-playwright:stable \
  pixi run --manifest-path /opt/pixi/pixi.toml pytest /workspace/tests/

Common Options

Volume Mounts

# Working directory
-v $(pwd):/workspace

# AWS credentials (read-only)
-v ~/.aws:/home/jovian/.aws:ro

# Kubernetes config (read-only)
-v ~/.kube:/home/jovian/.kube:ro

# SSH keys (read-only)
-v ~/.ssh:/home/jovian/.ssh:ro

# Git config
-v ~/.gitconfig:/home/jovian/.gitconfig:ro

Port Publishing

# JupyterLab
-p 8888:8888

# VNC
-p 5900:5900

# Multiple ports
-p 8888:8888 -p 5900:5900

Environment Variables

# AWS
-e AWS_PROFILE=myprofile
-e AWS_DEFAULT_REGION=us-east-1

# CUDA
-e CUDA_VISIBLE_DEVICES=0,1

# General
-e MY_VAR=value

GPU Access

# NVIDIA (all GPUs)
--gpus all

# NVIDIA (specific GPU)
--gpus '"device=0"'

# AMD/Intel
--device=/dev/dri

Docker Compose

For multi-container setups:

# docker-compose.yml
version: '3.8'
services:
  jupyter:
    image: ghcr.io/atrawog/bazzite-ai-pod-jupyter:stable
    ports:
      - "8888:8888"
    volumes:
      - ./notebooks:/workspace
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  devops:
    image: ghcr.io/atrawog/bazzite-ai-pod-devops:stable
    volumes:
      - ./infrastructure:/workspace
      - ~/.aws:/home/jovian/.aws:ro
      - ~/.kube:/home/jovian/.kube:ro

docker compose up -d
docker compose exec jupyter bash

Troubleshooting

GPU Not Detected

# Verify GPU on host
nvidia-smi

# Check container toolkit
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

Permission Denied

Container runs as user jovian (UID 1000). If you get permission errors:

# Run as root (not recommended)
docker run --user root ...

# Better: fix host directory permissions
chmod 755 ./my-project

Out of Memory

# Limit memory
docker run --memory=8g --gpus all ...

# In Python, clear GPU memory
import torch
torch.cuda.empty_cache()

See Also