Dev Containers¶

Bazzite AI workloads work as Dev Containers for VS Code, GitHub Codespaces, and JetBrains IDEs.

Bazzite AI OS Users

If you're on Bazzite AI OS, use the ujust commands instead for integrated GPU support and systemd service management.

What are Dev Containers?¶

Dev Containers define development environments as code. Develop inside a container with everything pre-configured.

Benefits:

Consistent environments - Same tools for every developer
Instant onboarding - Clone repo, open in container, start coding
GPU support - Full CUDA access for ML development

Available Images¶

Image	GPU	Best For
nvidia-python	Yes	ML/AI development
jupyter	Yes	Data science, notebooks

Prerequisites¶

VS Code¶

Install VS Code
Install the Dev Containers extension
Docker or Podman installed and running

JetBrains IDEs¶

Install a JetBrains IDE (IntelliJ, PyCharm, etc.)
Docker or Podman installed and running
Gateway or built-in Dev Container support

GPU Support (Optional)¶

For GPU-enabled variants (jupyter, githubrunner):

# Linux with NVIDIA GPU
sudo apt-get install -y nvidia-container-toolkit  # Ubuntu/Debian
sudo dnf install -y nvidia-container-toolkit      # Fedora

Usage with VS Code¶

Quick Start¶

Clone or open your project in VS Code
Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
Select "Dev Containers: Reopen in Container"

VS Code automatically builds and starts the container.

Adding to Your Project¶

Create a devcontainer.json:

{
  "name": "ML Development",
  "image": "ghcr.io/atrawog/bazzite-ai-pod-jupyter:stable",
  "runArgs": ["--device=nvidia.com/gpu=all"],
  "remoteUser": "jovian",
  "workspaceFolder": "/workspace",
  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-toolsai.jupyter"
      ]
    }
  }
}

Usage with GitHub Codespaces¶

GitHub Codespaces automatically detects .devcontainer/ configurations.

Setup¶

Push .devcontainer/ folder to your repository
Go to your GitHub repository
Click Code → Codespaces → Create codespace
Select the devcontainer configuration

Codespace Configuration¶

For Codespaces, use the CPU variants (GPU not available in Codespaces):

{
  "name": "Development",
  "image": "ghcr.io/atrawog/bazzite-ai-pod-base:stable",
  "remoteUser": "jovian",
  "workspaceFolder": "/workspace"
}

Usage with devcontainer CLI¶

The devcontainer CLI enables command-line workflows:

Install¶

npm install -g @devcontainers/cli

Build¶

# Build specific variant
devcontainer build --workspace-folder . \
  --config .devcontainer/jupyter/devcontainer.json

# Build with no cache
devcontainer build --workspace-folder . \
  --config .devcontainer/devops/devcontainer.json \
  --no-cache

Start Container¶

devcontainer up --workspace-folder . \
  --config .devcontainer/jupyter/devcontainer.json

Execute Commands¶

# Run command in container
devcontainer exec --workspace-folder . \
  --config .devcontainer/jupyter/devcontainer.json \
  python --version

# Interactive shell
devcontainer exec --workspace-folder . \
  --config .devcontainer/jupyter/devcontainer.json \
  bash

Customization¶

Adding VS Code Extensions¶

{
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-toolsai.jupyter",
        "esbenp.prettier-vscode",
        "dbaeumer.vscode-eslint"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/opt/pixi/envs/default/bin/python"
      }
    }
  }
}

Adding Post-Create Commands¶

{
  "postCreateCommand": "pip install -r requirements.txt"
}

Mounting Additional Volumes¶

{
  "mounts": [
    "source=${localEnv:HOME}/.aws,target=/home/jovian/.aws,type=bind,readonly",
    "source=${localEnv:HOME}/.ssh,target=/home/jovian/.ssh,type=bind,readonly"
  ]
}

Environment Variables¶

{
  "containerEnv": {
    "AWS_PROFILE": "development",
    "CUDA_VISIBLE_DEVICES": "0"
  }
}

Troubleshooting¶

Container fails to start¶

# Check Docker/Podman is running
docker ps
# or
podman ps

# Rebuild without cache
devcontainer build --workspace-folder . \
  --config .devcontainer/jupyter/devcontainer.json \
  --no-cache

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 errors¶

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

# Fix host directory permissions
chmod 755 ./my-project

# Or run as root (not recommended)
# Add to devcontainer.json:
# "remoteUser": "root"

VS Code doesn't show variants¶

Ensure subdirectories exist in .devcontainer/
Each must have a devcontainer.json file
Reload VS Code: Command Palette → "Developer: Reload Window"