Skip to content

Dev Containers

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

What are Dev Containers?

Dev Containers are a standard for defining development environments as code. Instead of installing tools locally, you 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
  • Isolated dependencies - No conflicts with host system
  • GPU support - Full CUDA access for ML development

Available Configurations

Bazzite AI provides pre-configured devcontainer variants in .devcontainer/:

Variant GPU Docker Best For
base - - General development, CI/CD
jupyter Yes - ML/AI, data science
devops - Yes Cloud infrastructure, IaC
githubrunner Yes Yes CI/CD runners

Prerequisites

VS Code

  1. Install VS Code
  2. Install the Dev Containers extension
  3. Docker or Podman installed and running

JetBrains IDEs

  1. Install a JetBrains IDE (IntelliJ, PyCharm, etc.)
  2. Docker or Podman installed and running
  3. 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

  1. Clone or open your project in VS Code
  2. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
  3. Select "Dev Containers: Reopen in Container"
  4. Choose a variant from the list:
  5. base - CPU-only development
  6. jupyter - ML/AI with GPU
  7. devops - Cloud tools with Docker
  8. githubrunner - CI/CD runner

VS Code automatically builds and starts the container.

Using a Specific Variant

If your project has .devcontainer/devcontainer.json:

# Clone with devcontainer
git clone https://github.com/your/project.git
code project/
# VS Code prompts: "Reopen in Container"

Adding to Your Project

Copy a variant to your project:

# Example: Add jupyter variant
cp -r /path/to/bazzite-ai/.devcontainer/jupyter .devcontainer/

Or create a minimal 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

  1. Push .devcontainer/ folder to your repository
  2. Go to your GitHub repository
  3. Click Code → Codespaces → Create codespace
  4. 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

Variant Details

base (CPU-only)

Minimal development environment:

  • Core dev tools (gcc, make, cmake, ninja)
  • Language runtimes (Python, Node.js, Go, Rust)
  • Modern shell (Starship, fzf, zoxide, ripgrep, bat, eza)
  • Git, GitHub CLI

Best for: General development, testing, CI/CD

jupyter (ML/AI)

GPU-enabled data science:

  • Everything from base
  • JupyterLab + GPU access (CUDA, cuDNN)
  • ML frameworks (PyTorch, TensorFlow)
  • Data science tools (pandas, numpy, matplotlib)

Best for: Machine learning, AI research, data analysis

GPU configuration:

{
  "runArgs": ["--device=nvidia.com/gpu=all"]
}

devops (Cloud Tools)

Cloud infrastructure development:

  • Everything from base
  • AWS CLI, Scaleway CLI
  • Kubernetes tools (kubectl, kubectx, kubens, Helm)
  • Infrastructure as Code (OpenTofu)
  • Docker-outside-of-Docker

Best for: Infrastructure as code, K8s operations, container builds

Docker access:

The devops variant includes Docker-outside-of-Docker. Your host Docker daemon is accessible inside the container.

githubrunner (CI/CD)

GitHub Actions runner:

  • Everything from base
  • GitHub Actions runner binaries
  • GPU auto-detection
  • Docker socket access

Modes:

  • Ephemeral: Single job then exit
  • Persistent: Multiple jobs with auto token refresh

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

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

See Also