Documentation
Docker Images
Custom Images

Custom Images

Build custom Docker images tailored to your specific development needs.

Why Custom Images?

Build a custom image when you need:

  • Specific tool versions not in shai-mega
  • Specialized development tools
  • GPU support for ML/AI
  • Embedded development toolchains
  • Minimal footprint with only your tools
  • Company-specific tooling

Requirements

All Shai-compatible images must include these packages:

Required System Packages 

 1RUN apt-get update && apt-get install -y --no-install-recommends \
 2    supervisor \
 3    dnsmasq \
 4    iptables \
 5    tinyproxy \
 6    bash \
 7    ca-certificates \
 8    coreutils \
 9    curl \
10    iproute2 \
11    iputils-ping \
12    jq \
13    net-tools \
14    passwd \
15    procps \
16    sed \
17    util-linux \
18    && rm -rf /var/lib/apt/lists/*
Shortcut: Base your image on ghcr.io/colony-2/shai-base:latest which includes all requirements.

Supervisord Installation

Shai requires supervisord to be installed. This is automatic if you base on shai-base.

If building from scratch, ensure supervisord is installed and in PATH. The bootstrap process automatically starts supervisord and loads service configurations from /etc/supervisor/conf.d/*.conf.

Building from shai-base

Example: Python ML Development 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Python and ML tools
 4RUN apt-get update && apt-get install -y --no-install-recommends \
 5    python3.11 \
 6    python3-pip \
 7    python3-dev \
 8    build-essential \
 9    && rm -rf /var/lib/apt/lists/*
10
11# Install ML frameworks
12RUN pip3 install --no-cache-dir \
13    numpy \
14    pandas \
15    scikit-learn \
16    torch \
17    transformers \
18    jupyter
19
20# Install development tools
21RUN pip3 install --no-cache-dir \
22    black \
23    ruff \
24    mypy \
25    pytest
26
27WORKDIR /src

Example: Go Development 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Go 1.21
 4ARG GO_VERSION=1.21.6
 5RUN curl -fsSL https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz | \
 6    tar -C /usr/local -xzf -
 7
 8ENV PATH="/usr/local/go/bin:${PATH}"
 9ENV GOPATH="/go"
10
11# Install Go tools
12RUN go install golang.org/x/tools/gopls@latest && \
13    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest && \
14    go install github.com/go-delve/delve/cmd/dlv@latest
15
16WORKDIR /src

Example: Rust Development 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Rust
 4ENV RUSTUP_HOME=/usr/local/rustup \
 5    CARGO_HOME=/usr/local/cargo \
 6    PATH=/usr/local/cargo/bin:$PATH
 7
 8RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
 9    sh -s -- -y --default-toolchain stable --profile minimal
10
11# Install Rust tools
12RUN cargo install cargo-watch cargo-edit cargo-audit
13
14# Install build dependencies
15RUN apt-get update && apt-get install -y --no-install-recommends \
16    build-essential \
17    pkg-config \
18    libssl-dev \
19    && rm -rf /var/lib/apt/lists/*
20
21WORKDIR /src

Example: Node.js Specific Version 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Node.js 18 LTS
 4RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \
 5    apt-get install -y --no-install-recommends nodejs && \
 6    rm -rf /var/lib/apt/lists/*
 7
 8# Install pnpm
 9RUN npm install -g pnpm
10
11# Install global tools
12RUN pnpm install -g \
13    typescript \
14    tsx \
15    @nestjs/cli \
16    prisma
17
18WORKDIR /src

Specialized Images

GPU Support (PyTorch) 

 1FROM nvidia/cuda:12.1.0-cudnn8-devel-ubuntu22.04
 2
 3# Install Shai requirements first
 4RUN apt-get update && apt-get install -y --no-install-recommends \
 5    supervisor \
 6    dnsmasq \
 7    iptables \
 8    tinyproxy \
 9    bash \
10    ca-certificates \
11    coreutils \
12    curl \
13    iproute2 \
14    iputils-ping \
15    jq \
16    net-tools \
17    passwd \
18    procps \
19    sed \
20    util-linux \
21    python3.10 \
22    python3-pip \
23    && rm -rf /var/lib/apt/lists/*
24
25# Install PyTorch with CUDA support
26RUN pip3 install --no-cache-dir \
27    torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
28
29# Install ML tools
30RUN pip3 install --no-cache-dir \
31    transformers \
32    accelerate \
33    datasets \
34    wandb
35
36WORKDIR /src

Usage:

1# .shai/config.yaml
2apply:
3  - path: ml/training
4    image: ghcr.io/my-org/pytorch-gpu:latest
5    resources: [gpu-access]

Embedded Development (ARM) 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install ARM toolchain
 4RUN apt-get update && apt-get install -y --no-install-recommends \
 5    gcc-arm-none-eabi \
 6    gdb-multiarch \
 7    openocd \
 8    picocom \
 9    && rm -rf /var/lib/apt/lists/*
10
11# Install Rust for embedded
12ENV RUSTUP_HOME=/usr/local/rustup \
13    CARGO_HOME=/usr/local/cargo \
14    PATH=/usr/local/cargo/bin:$PATH
15
16RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
17    sh -s -- -y --default-toolchain stable
18
19# Add ARM targets
20RUN rustup target add thumbv7em-none-eabihf thumbv6m-none-eabi
21
22# Install cargo-embed and probe-rs
23RUN cargo install cargo-embed probe-rs
24
25WORKDIR /src

DevOps Tools 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install cloud CLIs
 4RUN curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" && \
 5    unzip awscliv2.zip && \
 6    ./aws/install && \
 7    rm -rf aws awscliv2.zip
 8
 9# Install kubectl
10RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
11    install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
12
13# Install Terraform
14ARG TERRAFORM_VERSION=1.6.0
15RUN curl -fsSL https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip -o terraform.zip && \
16    unzip terraform.zip && \
17    mv terraform /usr/local/bin/ && \
18    rm terraform.zip
19
20# Install Pulumi
21RUN curl -fsSL https://get.pulumi.com | sh
22
23ENV PATH="/root/.pulumi/bin:${PATH}"
24
25WORKDIR /src

Multi-Stage Builds

Reduce final image size with multi-stage builds:

 1# Stage 1: Build dependencies
 2FROM ghcr.io/colony-2/shai-base:latest as builder
 3
 4RUN apt-get update && apt-get install -y build-essential
 5# ... build steps ...
 6
 7# Stage 2: Runtime
 8FROM ghcr.io/colony-2/shai-base:latest
 9
10# Copy only what's needed
11COPY --from=builder /path/to/binaries /usr/local/bin/
12
13WORKDIR /src

Best Practices

✅ Do

  1. Base on shai-base for automatic requirements:

    1FROM ghcr.io/colony-2/shai-base:latest

  2. Clean up apt lists to reduce size:

    1RUN apt-get update && apt-get install -y package \
2    && rm -rf /var/lib/apt/lists/*

  3. Use –no-install-recommends to avoid bloat:

    1RUN apt-get install -y --no-install-recommends package

  4. Combine RUN commands to reduce layers:

    1RUN apt-get update && \
2    apt-get install -y pkg1 pkg2 && \
3    rm -rf /var/lib/apt/lists/*

  5. Version pin critical tools:

    1ARG GO_VERSION=1.21.6
2RUN curl -fsSL https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz

  6. Document requirements in README

  7. Test with Shai before publishing

❌ Don’t

  1. Don’t forget Shai requirements if not basing on shai-base
  2. Don’t leave apt lists (/var/lib/apt/lists/*)
  3. Don’t run as root (Shai handles user creation)
  4. Don’t hardcode secrets in the image
  5. Don’t use latest tags for critical dependencies
  6. Don’t include sensitive data in layers

Building and Publishing

Build Locally 

1docker build -t my-org/my-shai-image:latest .

Test with Shai 

1shai --image my-org/my-shai-image:latest -rw src --verbose

Publish to Registry 

1# GitHub Container Registry
2docker tag my-org/my-shai-image:latest ghcr.io/my-org/my-shai-image:latest
3docker push ghcr.io/my-shai-image:latest
4
5# Docker Hub
6docker tag my-org/my-shai-image:latest my-org/my-shai-image:latest
7docker push my-org/my-shai-image:latest

Use in Configuration 

1# .shai/config.yaml
2type: shai-sandbox
3version: 1
4image: ghcr.io/my-org/my-shai-image:latest

Testing Custom Images

Verify Requirements 

1# Check required packages
2shai --image my-image:latest -- bash -c "
3  which supervisord && \
4  which dnsmasq && \
5  which iptables && \
6  which tinyproxy && \
7  echo 'All requirements present'
8"

Test Sandboxing 

1# Verify network filtering works
2shai --image my-image:latest --verbose -rw . -- bash -c "
3  cat /var/log/shai/iptables.out
4"

Test Your Tools 

1# Verify your custom tools
2shai --image my-image:latest -- bash -c "
3  go version && \
4  python3 --version && \
5  cargo --version
6"

Example: Complete Custom Image 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3LABEL org.opencontainers.image.source=https://github.com/my-org/my-repo
 4LABEL org.opencontainers.image.description="Custom Shai image for XYZ project"
 5
 6# Install system dependencies
 7RUN apt-get update && apt-get install -y --no-install-recommends \
 8    build-essential \
 9    pkg-config \
10    libssl-dev \
11    git \
12    vim \
13    && rm -rf /var/lib/apt/lists/*
14
15# Install Python 3.11
16RUN apt-get update && apt-get install -y --no-install-recommends \
17    python3.11 \
18    python3-pip \
19    python3-venv \
20    && rm -rf /var/lib/apt/lists/*
21
22# Install Python packages
23RUN pip3 install --no-cache-dir \
24    fastapi \
25    uvicorn \
26    sqlalchemy \
27    alembic \
28    pytest \
29    black \
30    mypy
31
32# Install Node.js 20
33RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
34    apt-get install -y --no-install-recommends nodejs && \
35    rm -rf /var/lib/apt/lists/*
36
37# Install global npm tools
38RUN npm install -g typescript prettier eslint
39
40# Set working directory
41WORKDIR /src
42
43# Health check (optional)
44HEALTHCHECK --interval=30s --timeout=3s \
45  CMD which supervisord || exit 1

Troubleshooting

Shai fails to start

Check: Are all required packages present?

1docker run --rm my-image:latest bash -c "which supervisord dnsmasq iptables tinyproxy"

Network filtering doesn’t work

Check: iptables and networking tools installed

1docker run --rm my-image:latest bash -c "iptables --version"

Permission issues

Check: Don’t run commands as a specific user in the Dockerfile - Shai handles user creation

Next Steps

shai-mega