> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a custom image

> Create your own custom image in Workspace on VESSL

# Requirements

To use custom images to run a workspace, your custom images have to satisfy below requirements.

* Jupyterlab
  * VESSL runs Jupyterlab and expose port `8888`. Jupyterlab should be pre-installed in the container image.
  * Jupyterlab daemon must be located in `/usr/local/bin/jupyter`.
* sshd
  * VESSL runs sshd and expose port `22` as NodePort. sshd package should be pre-installed in the container image.
* Persistent Volume Claim (PVC) mountable at `/root`
  * VESSL mounts a PVC at `/root` to keep state across Pod restarts.
* curl
  * VESSL verifies workspace status. `curl` package should be pre-installed in the container image.

# Building from VESSL's pre-built images

VESSL offers pre-built images to run workspaces directly. You can use these images to build your own images. These images already have pre-installed Jupyterlab and sshd. The list of images is in the following table.

## CPU pre-built images

| Python | Tensorflow | PyTorch | Torchvision | Image                          |
| ------ | ---------- | ------- | ----------- | ------------------------------ |
| 3.8    | 2.12.0     | 1.13.1  | 0.14.1      | `quay.io/vessl-ai/python:3.8`  |
| 3.9    | 2.12.0     | 1.13.1  | 0.14.1      | `quay.io/vessl-ai/python:3.9`  |
| 3.10   | 2.12.0     | 1.13.1  | 0.14.1      | `quay.io/vessl-ai/python:3.10` |
| 3.11   | 2.12.0     | 2.0.1   | 0.15.2      | `quay.io/vessl-ai/python:3.11` |

## GPU pre-built images

| Python | CUDA | TensorFlow | PyTorch | Image                                         |
| ------ | ---- | ---------- | ------- | --------------------------------------------- |
| 3.10   | 12.1 | -          | 2.3.1   | `quay.io/vessl-ai/torch:2.3.1-cuda12.1`       |
| 3.10   | 11.8 | -          | 2.2.2   | `quay.io/vessl-ai/torch:2.2.2-cuda11.8`       |
| 3.10   | 12.2 | -          | 2.1.0   | `quay.io/vessl-ai/torch:2.1.0-cuda12.2`       |
| 3.8    | 12.0 | -          | 1.14.0  | `quay.io/vessl-ai/torch:1.14.0-cuda12.0`      |
| 3.10   | 12.3 | 2.14.0     | -       | `quay.io/vessl-ai/tensorflow:2.14.0-cuda12.3` |
| 3.10   | 12.4 | -          | -       | `quay.io/vessl-ai/cuda:12.4`                  |
| 3.10   | 12.1 | -          | -       | `quay.io/vessl-ai/cuda:12.1`                  |
| 3.10   | 11.8 | -          | -       | `quay.io/vessl-ai/cuda:11.8`                  |

## Example

```dockerfile theme={null}
# Use CUDA 12.1, PyTorch 2.3.1 base image
FROM quay.io/vessl-ai/torch:2.3.1-cuda12.1

# Install custom Python dependencies
RUN pip install transformers
...
```

# Building from community-maintained images

You can make your own images from any community-maintained Docker images. Make sure that your image meet our requirements.

## Example

```dockerfile theme={null}
FROM nvidia/cuda:11.2.2-devel-ubuntu20.04

RUN apt-get update
RUN DEBIAN_FRONTEND=noninteractive \
    apt-get install -y \
    software-properties-common curl openssh-server

# Install Python 3.9
# Note that base image has python3.8 (3.8.10) installed
RUN add-apt-repository ppa:deadsnakes/ppa
RUN apt-get install -y python3.9 python3.9-distutils
# Add symbolic links
RUN update-alternatives --install /usr/bin/python3 python3 $(which python3.9) 1
RUN update-alternatives --install /usr/bin/python python /usr/bin/python3 1

# Install pip
RUN curl https://bootstrap.pypa.io/get-pip.py | python
RUN pip install -U pip

# Install Jupyterlab
RUN pip install jupyterlab
```

# FAQ

If you use `conda` to install JupyterLab, the JupyterLab executable is generally located at `/opt/conda/bin/jupyter`. In this case, you should create a symbolic link at `usr/local/bin/jupyter`.

```dockerfile theme={null}
# In Dockerfile,
RUN ln -s /opt/conda/bin/jupyter /usr/local/bin/jupyter
```