Skip to content

v3 (jippi/docker-pixelfed)

This doc is WIP and may include wrong or incomplete information

v2 to v3?!... oh no, not again!

Docker Compose v2 was a huge change, requiring a lot of (risky) work to get migrated. v3 will be significantly smaller, and should largely be a drop-in experience, outside of some relatively simple cleanup/move-files-around tasks due to docker-pixelfed not being in the main source tree any more.

Changes made from between the Docker Compose v2 version in upstream Pixelfed and this project.

This document assume you are running Docker Compose v2 already and is looking to move to v3.

Breaking Changes

These changes are breaking, removing, or changing existing behavior from Docker Compose v1 and requires your attention and possibly some steps to fix.

Breaking Change New Docker image names

Since docker-pixelfed do not exist within the pixelfed project itself, the URL for the container images will change.

Before you might have something like the following in your .env file

DOCKER_APP_DEBIAN_RELEASE="bullseye"
DOCKER_APP_IMAGE="ghcr.io/jippi/pixelfed"
DOCKER_APP_PHP_VERSION="8.2"
DOCKER_APP_RELEASE="jippi-fork-1"

Those are now

# [v0] for the least v0.x.y release of Pixelfed
# [v0.12] for the least v0.12.x release of Pixelfed
# [v0.12.1] for the v0.12.1 release of Pixelfed
DOCKER_APP_RELEASE="v0.12.1"

# changed from ghcr.io/jippi/pixelfed
DOCKER_APP_IMAGE="ghcr.io/jippi/docker-pixelfed"

# changed from "bullseye"
DOCKER_APP_DEBIAN_RELEASE="bookworm"

# We only build PHP 8.3 now, so 8.2 or 8.1 is not supported
DOCKER_APP_PHP_VERSION="8.3"

# Different format
DOCKER_APP_TAG="${DOCKER_APP_RELEASE:?missing}-${DOCKER_APP_RUNTIME:?missing}-${DOCKER_APP_PHP_VERSION:?missing}-${DOCKER_APP_DEBIAN_RELEASE:?missing}"

Breaking Change Splitting the Dockerfile

v3 splits the Dockerfile into two to keep them focused, and reducing build times, by having higher cache utilization.

  • One for the "PHP" container (package, source)
    • System packages
    • PHP
    • PECL extensions
    • Composer
  • One for the runtime Pixelfed container (package, source)
    • Pixelfed Source Code
    • Apache / nginx / FPM
    • Docker Entrypoint (and it's scripts)

This should not directly impact most users, as any custom build you did before (custom PHP extensions, frontend, etc.) can still be done against the runtime Docker image.

No latest tags

latest tags are typically pretty dangerous to use, especially in a fast-moving project such as Pixelfed where things might break in patch releases.

See the dedicated tags documentation for more information

No fpm runtime { data-toc-label="No FPM runtime" }

v3 only builds apache (with mod_php) and nginx (with fpm) runtimes now.

The fpm runtime was quite an edge-case, not likely to be relevant for majority of folks (reach out if you are missing this!)

New or improved features

All the new and exciting features and capabilities. 🚀

This is where we hope we can convince you that the breaking changes and migration work was worth it ❤

Improvement Nightly builds

We will now automatically create nightly builds of Pixelfed from the dev and staging branches.

See the dedicated tags documentation for more information