Skip to main content

Image requirements

This document outlines the specifications for creating a standardized image used in Anyscale infrastructure. It details the system requirements, essential software packages, and the Python libraries needed to ensure compatibility and performance in Anyscale environments.

System requirements​

  • Base image: Use ubuntu:22.04 as image foundation, ensuring a stable and widely supported Linux environment.
  • User configuration: Include ray user with user ID 1000 and group ID 100. Also, ray needs to able to run sudo without a password.
  • Working directory: Set WORKDIR to /home/ray, which designates the primary directory for user operations and application execution. Ensure that the ray user has read and write permissions to this directory.
  • Home directory: Set /home/ray as HOME, centralizing user configurations and runtime files.

System​

  • sudo
  • python
  • bash
  • openssh-server
  • openssh-client
  • rsync
  • zip
  • unzip
  • git
  • gdb
  • curl

Python​

  • ray>=2.7
  • anyscale
  • packaging
  • boto3
  • google
  • google-cloud-storage
  • jupyterlab

Anyscale reserved resources​

Filesystem Paths:​

  • /etc/anyscale
  • /opt/anyscale
  • /tmp/anyscale
  • /tmp/ray
  • /mnt/

Network Ports:​

80, 443, 1010, 1012, 2222, 5555, 5903, 6379, 6822, 6823, 6824, 6826, 7878, 8000 ,8076, 8085, 8201, 8265, 8266, 8686, 8687, 8912, 8999, 9090, 9092, 9100, 9478 ,9479, 9480, 9481, 9482

Workspace Dependencies​

If the image is intended to run on Workspaces, the following additional dependencies are required:

  • Persistent Bash History: Add PROMPT_COMMAND="history -a" to /home/ray/.bashrc to ensure that the bash history is saved after each command.
  • Source .workspacerc: source ~/.workspacerc if it exists.

Example Dockerfile​

# syntax=docker/dockerfile:1.3-labs

# Specify the Ray Version and Python Version to use. You can override this setting at build time.
# Note that the ubuntu:22.04 base image is always Python 3.10.
# You are responsible for installing other versions of Python based on your application requirements.
ARG RAY_VERSION=2.39.0
ARG PYTHON_MAJOR_VERSION=3
ARG PYTHON_MINOR_VERSION=10

# Define the Anyscale image as a named build stage
ARG ANYSCALE_RAY_IMAGE=anyscale/ray:$RAY_VERSION-py$PYTHON_MAJOR_VERSION$PYTHON_MINOR_VERSION
FROM $ANYSCALE_RAY_IMAGE as anyscale-ray

# Base image
FROM ubuntu:22.04 as base

# Redeclare the RAY_VERSION and PYTHON_VERSION variables to make it available in the base image
ARG RAY_VERSION
ARG PYTHON_MAJOR_VERSION
ARG PYTHON_MINOR_VERSION

ENV DEBIAN_FRONTEND=noninteractive

# Install basic dependencies and setup `ray` user with sudoer permissions.
# Note that `ray` user should be (uid: 1000, gid: 100) to work with shared file
# systems.
# Add gdb since Ray dashboard uses `memray attach`, which requires gdb.
RUN <<EOF
#!/bin/bash
set -euxo pipefail

apt-get update -y
apt-get install -y --no-install-recommends sudo tzdata openssh-client openssh-server rsync zip unzip git gdb
# Install Python -- you can replace this with whatever Python installation method
# you want (i.e. conda, etc...), as long as `python` is on PATH. At runtime
# we'll source `/home/ray/.bashrc` in case you modify PATH there. This example uses
# virtualenv
apt-get install -y python3-venv

apt-get clean
rm -rf /var/lib/apt/lists/*

# Work around for https://bugs.launchpad.net/ubuntu/+source/openssh/+bug/45234
mkdir -p /var/run/sshd

useradd -ms /bin/bash -d /home/ray ray --uid 1000 --gid 100
usermod -aG sudo ray
echo 'ray ALL=NOPASSWD: ALL' >> /etc/sudoers
EOF

# Switch to `ray` user
USER ray
ENV HOME=/home/ray
ENV PATH=/home/ray/virtualenv/bin:$PATH

RUN <<EOF
#!/bin/bash
# Run as user `ray` from here.
su --login ray
python3 -m venv --system-site-packages /home/ray/virtualenv
export PATH=/home/ray/virtualenv/bin:$PATH

# You only need jupyterlab if you want to access Jupyter notebooks from the Anyscale workspace web UI.
# Note that this only installs `ray[default]` to minimize the amount of dependencies.
# You can add extra libraries such as Ray Tune with `ray[default,tune]` or all of them with `ray[all]`.
# See the Ray docs for more info: https://docs.ray.io/en/latest/ray-overview/installation.html
pip install --no-cache-dir anyscale jupyterlab ray[default]==${RAY_VERSION}

# If you want to run your cluster on Amazon Web Services, uncomment out the following lines.
# curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
# unzip awscliv2.zip && sudo ./aws/install && rm awscliv2.zip

# If you want to run your cluster on Google Cloud Platform, uncomment the following line.
# pip install --no-cache-dir google google-cloud-storage

# Start of workspace dependencies: this section is only needed if you want your image to run on workspaces.

# This flushes bash history after each command, so that workspaces can persist it.
echo 'PROMPT_COMMAND="history -a"' >> /home/ray/.bashrc

# If the workspacerc exists, load it.
echo '[ -e ~/.workspacerc ] && source ~/.workspacerc' >> /home/ray/.bashrc

EOF

# Copying RayTurbo files and requirements
COPY --from=anyscale-ray /opt/anyscale /opt/anyscale
RUN pip install -r /opt/anyscale/runtime-requirements.txt

# Environment setup for RayTurbo
ENV ANYSCALE_RAY_SITE_PKG_DIR=/home/ray/virtualenv/lib/python${PYTHON_MAJOR_VERSION}.${PYTHON_MINOR_VERSION}/site-packages