FAQ: Can I use custom Docker images on VOLT?

Yes. VOLT supports deploying custom Docker images from Docker Hub, GitHub Container Registry (GHCR), AWS ECR, Google Container Registry (GCR), or private registries. Simply specify your image name in the deployment command, and VOLT pulls and runs it on your selected GPU—no special configuration needed.

All NVIDIA CUDA images work out-of-the-box with GPU passthrough automatically configured. Use private images by providing registry credentials, and leverage VOLT's image caching for faster subsequent deployments.

Deploy Custom Image

From Docker Hub:

# Public image
volt deploy --image myusername/my-ml-app:latest --gpu A100

# Private image (provide credentials)
volt login-registry docker.io --username myuser --password $DOCKER_PASSWORD
volt deploy --image myusername/private-ml-app:latest --gpu A100

From GitHub Container Registry:

# Login to GHCR
echo $GITHUB_TOKEN | volt login-registry ghcr.io --username myusername --password-stdin

# Deploy image
volt deploy --image ghcr.io/myorg/my-app:v1.2.3 --gpu A100

From AWS ECR:

# Login to ECR
aws ecr get-login-password --region us-west-2 | \
  volt login-registry 123456789.dkr.ecr.us-west-2.amazonaws.com --username AWS --password-stdin

# Deploy image
volt deploy --image 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:latest --gpu A100

From Google Container Registry:

# Login to GCR
cat keyfile.json | volt login-registry gcr.io --username _json_key --password-stdin

# Deploy image
volt deploy --image gcr.io/my-project/my-app:latest --gpu A100

Dockerfile Best Practices

Base Image Selection:

# Use NVIDIA CUDA base images for GPU support
FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04

# Or use framework-specific images
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

# Or use Jupyter images
FROM jupyter/pytorch-notebook:latest

Example: Custom Training Image

FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    wget \
    libsndfile1 \
    && rm -rf /var/lib/apt/lists/*

# Install Python packages
COPY requirements.txt /workspace/
RUN pip install --no-cache-dir -r /workspace/requirements.txt

# Copy application code
COPY ./src /workspace/src
COPY ./models /workspace/models

# Set working directory
WORKDIR /workspace

# Environment variables
ENV PYTHONUNBUFFERED=1
ENV CUDA_VISIBLE_DEVICES=0,1,2,3

# Entry point
CMD ["python", "src/train.py"]

requirements.txt:

transformers==4.36.0
accelerate==0.25.0
bitsandbytes==0.41.3
datasets==2.16.0
peft==0.7.0
trl==0.7.4
wandb==0.16.1

Build and Push:

# Build image
docker build -t myusername/training-app:v1 .

# Test locally (if you have GPU)
docker run --gpus all myusername/training-app:v1

# Push to registry
docker push myusername/training-app:v1

# Deploy on VOLT
volt deploy --image myusername/training-app:v1 --gpu A100 --count 4

Multi-Stage Builds (Optimize Image Size)

# Build stage
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-devel AS builder

WORKDIR /build
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# Runtime stage (smaller image)
FROM pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime

COPY --from=builder /root/.local /root/.local
COPY ./src /workspace/src

ENV PATH=/root/.local/bin:$PATH
WORKDIR /workspace

CMD ["python", "src/train.py"]

GPU Access in Container

Verify GPU Available:

# Add healthcheck to Dockerfile
HEALTHCHECK CMD nvidia-smi || exit 1

Test GPU access after deployment:

# Check GPUs detected
volt exec my-instance -- nvidia-smi

# Run Python GPU test
volt exec my-instance -- python -c "import torch; print(f'GPUs: {torch.cuda.device_count()}')"

Environment Variables

Pass secrets securely:

# Don't bake secrets into image
# Pass at deployment time
volt deploy --image my-app:latest \
  --gpu A100 \
  --env HUGGINGFACE_TOKEN=$HF_TOKEN \
  --env AWS_ACCESS_KEY_ID=$AWS_KEY \
  --env AWS_SECRET_ACCESS_KEY=$AWS_SECRET \
  --env WANDB_API_KEY=$WANDB_KEY \
  --name secure-app

Use .env file:

# Create .env file
cat > .env << EOF
HUGGINGFACE_TOKEN=hf_xxx
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=xxx
WANDB_API_KEY=xxx
EOF

# Deploy with env file
volt deploy --image my-app:latest --gpu A100 --env-file .env

Private Registry

Self-Hosted Registry:

# Login to private registry
volt login-registry registry.mycompany.com:5000 \
  --username admin \
  --password $REGISTRY_PASSWORD

# Deploy from private registry
volt deploy --image registry.mycompany.com:5000/ml-models/llama-finetune:v2 \
  --gpu H100

Image Caching

VOLT caches frequently-used images for faster deployment:

# First deployment: Image pulled (60-180 seconds)
volt deploy --image myimage:latest --gpu A100

# Subsequent deployments: Cached (10-20 seconds)
volt deploy --image myimage:latest --gpu A100 --name second-instance

Force re-pull:

# Pull latest image even if cached
volt deploy --image myimage:latest --gpu A100 --pull always

Debugging Container Issues

View logs:

# Container startup logs
io logs my-instance

# Follow logs in real-time
io logs my-instance --follow

# Last 100 lines
io logs my-instance --tail 100

Interactive debugging:

# SSH into running container
io ssh my-instance

# Or execute bash
volt exec my-instance -- /bin/bash

Image troubleshooting:

# Test image locally before deployment
docker run --gpus all -it myimage:latest /bin/bash

# Check image size (should be < 10GB ideally)
docker images myimage:latest

# Inspect image layers
docker history myimage:latest

Best Practices

Use specific tags (not latest):
```bash
# Good: versioned tag
volt deploy --image myapp:v1.2.3 --gpu A100

# Bad: latest tag (unpredictable)
volt deploy --image myapp:latest --gpu A100
```

Minimize image size:
- Use -slim or -alpine variants when possible
- Remove build tools in production images
- Use .dockerignore to exclude unnecessary files
Pin dependency versions:
dockerfile # requirements.txt torch==2.1.0 transformers==4.36.0 # Avoid: torch>=2.0 (unpredictable)
Set proper working directory:
dockerfile WORKDIR /workspace # All paths relative to /workspace

Deploy custom Docker images on VOLT with full GPU support and private registry integration.