From be98c04d0d8d651bcd20b55edebcbd544670e4b3 Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Wed, 15 Apr 2026 15:20:53 +0200 Subject: [PATCH] Docker: Document directory layout and legacy image policy in README.md Signed-off-by: Michael Mayer --- docker/README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docker/README.md b/docker/README.md index c3eb51c27..a0e5b83b9 100644 --- a/docker/README.md +++ b/docker/README.md @@ -19,3 +19,36 @@ See our [Getting Started FAQ](https://docs.photoprism.app/getting-started/faq/#h ### Why Not Use Virtual Machines Instead? A virtual machine with a dedicated operating system environment provides even more security, but usually has side effects such as lower performance and more difficult handling. Using a VM, however, doesn't prevent you from running containerized apps to get the best of both worlds. This is essentially what happens when you install Docker on [virtual cloud servers](https://docs.photoprism.app/getting-started/cloud/digitalocean/) and operating systems other than Linux. + +### Directory Overview + +| Directory | Purpose | +|---------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `develop/` | Development images used as the base for the production image and by contributors to build and test PhotoPrism in a reproducible environment. | +| `photoprism/` | Production (runtime) images published as [`photoprism/photoprism`](https://hub.docker.com/r/photoprism/photoprism) on Docker Hub. | +| `tensorflow/` | Helper image used to build and package the TensorFlow C library shipped with PhotoPrism. | +| `demo/` | Build context for the public [demo site](https://demo.photoprism.app/), including Traefik and job configuration. | +| `ddns/` | Minimal image for the Dynamic DNS updater used by our hosted services. | +| `dummy/` | Test doubles for OIDC and WebDAV used by acceptance tests and local development. | +| `goproxy/` | Caching Go module proxy used to speed up CI and local builds. | + +### Which Image Should I Use? + +> **Use the latest image whenever possible.** The base image used by the top-level [`Dockerfile`](../Dockerfile) is recommended for development. Currently, this is Ubuntu 25.10 ("Questing Quokka"), i.e. `photoprism/develop:questing` and `photoprism/photoprism:questing`. + +New container deployments should pull the `:latest` tag (or an explicit current release tag) from Docker Hub. Contributors setting up a local development environment should follow the [Developer Guide](https://docs.photoprism.app/developer-guide/setup/), which is kept in sync with the top-level `Dockerfile` and `compose.yaml`. + +### Legacy Images ("Use at Your Own Risk") + +The `develop/` and `photoprism/` directories also contain Dockerfiles for a number of **older Linux distributions**, for example Ubuntu *Jammy*, *Noble*, *Oracular*, *Plucky*, *Impish*, *Lunar*, *Mantic* and Debian *Buster*, *Bullseye*, *Bookworm*, as well as an `armv7` variant. + +These files are **kept for documentation and reference purposes only**: + +- Their base images, system packages, and bundled dependencies (for example `libvips`, `libheif`, `ffmpeg`, `exiftool`, `darktable`) are typically outdated and may contain unpatched security vulnerabilities. +- We **no longer build, publish, or test** these images as part of our regular release process. +- Features and bug fixes added to the current image are not backported. +- Compatibility with current Go dependencies (notably C bindings such as [`govips`](https://github.com/davidbyttow/govips), [`onnxruntime_go`](https://github.com/yalue/onnxruntime_go), and the TensorFlow C API) is **not guaranteed** — a successful build on an older base does not imply a working runtime. + +If you still need to build one of these images, consider it **"use at your own risk"**: you may need to upgrade individual system packages (for example pulling `libvips` from a backport PPA, as `scripts/dist/install-libvips.sh` does for Ubuntu Jammy), adjust pinned Go dependencies, or patch the Dockerfile to match the current upstream. Please do not open issues for problems that only affect legacy images. + +For questions about supported environments and current system requirements, see the [System Requirements](https://docs.photoprism.app/getting-started/#system-requirements) documentation.