Writing Docker Images¶

Docker Basics¶

Using pip¶

Typically when writing Dockerfiles it is a good idea to use a first-party base images (i.e. debian:buster-slim) as derived images can sometimes be unmaintained and unknowable black boxes.

It should generally work fine to just use a first party base image and install trimesh via pip which always has the latest version:

FROM python:3.11-slim-bullseye
RUN pip install trimesh[easy]

Using Prebuilt Images¶

The trimesh/trimesh docker images are based on the official Python base image, currently python:3.11-slim-bullseye. They are built and pushed to Docker Hub automatically in Github Actions for every release.

If you need some of the more demanding dependencies they can be a good option. The trimesh/trimesh images are pushed with three tags: latest (for latest :), semantic version (i.e. 3.15.5), or git short hash (i.e. 1c6178d). These images include embree and trimesh[all] which is run in a multi-stage build to avoid including intermediate files in the final image.

They run as the non-root user user and the working directory is /home/user. A minimal docker file could look like:

FROM trimesh/trimesh:latest

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY app.py .
CMD python app.py

Which you could then save as the file Dockerfile and build with:

docker build . -t example
docker run -t example

Building Trimesh Images¶

Trimesh is using a multistage build to avoid copying in things like g++, so you have to explicitly specify that you want to build the output target. You also probably need to enable BuildKit:

DOCKER_BUILDKIT=1 docker build --target output -t trimesh/trimesh:latest .

There is also a Makefile which enables Buildkit, tags the versioned images, and provides access to other targets like test and docs:

# will list the available options
make help

# will build and tag a `trimesh/trimesh:latest` image
# and also tag it with semantic version and git hash
make build

# will build trimesh images and then in a different
# build stage install the testing requirements and
# run all of trimesh's unit tests inside the image
make test

# will build trimesh's docs inside the image and then
# eject the results into the `./html` directory
make docs