Skip to content

Build settings

If anything is confusing, unclear, missing, or maybe even wrong on this page, then please let us know by submitting a bug report ❤

A custom build requires the Pixelfed source code locally

The Dockerfile build system requires that you have pixelfed/pixelfed source code in ./src, in the root of the project, next to the Docker Compose file.

You can run git clone https://github.com/pixelfed/pixelfed.git ./src to get the Pixelfed source code from GitHub, from there, you can check out the desired branch or tag you want to include in your local build.

This, of course, also works with any Pixelfed fork, as long as the PHP source code for Pixelfed (or a fork of Pixelfed) exists in ./src

Most of these build arguments is configurable in your .env file when using the compose.yaml from Pixelfed!

The Pixelfed Dockerfile utilizes Docker Multi-stage builds and Build arguments.

Using build arguments allows us to create a flexible and more maintainable Dockerfile, supporting multiple runtimes (Nginx and Apache + mod_php) and end-user flexibility without having to fork or copy the Dockerfile.

Build arguments can be configured using --build-arg 'name=value' for docker build, docker compose build and docker buildx build. For compose.yaml, the args key for build can be used.

Most settings have two names in the title. The first one is the build arg name (--build-arg) and the second is the name in your .env file when using Docker Compose

PHP_VERSION

Named DOCKER_APP_PHP_VERSION in your .env file

The PHP version to use when building the runtime container.

Any valid Docker Hub PHP version is acceptable here, as long as it's published to Docker Hub

Example values:

  • 8 will use the latest version of PHP 8
  • 8.1 will use the latest version of PHP 8.1
  • 8.2.14 will use PHP 8.2.14
  • latest will use whatever is the latest PHP version

Default value: 8.3

PHP_PECL_EXTENSIONS

PECL extensions to install via pecl install

Use PHP_PECL_EXTENSIONS_EXTRA if you want to add additional extenstions.

Only change this setting if you want to change the baseline extensions.

See the PECL extensions documentation on Docker Hub for more information.

Default value: imagick redis

PHP_PECL_EXTENSIONS_EXTRA

Named DOCKER_APP_PHP_PECL_EXTENSIONS_EXTRA in your .env file

Extra PECL extensions (separated by space) to install via pecl install

See the PECL extensions documentation on Docker Hub for more information.

Default value: ""

PHP_EXTENSIONS

PHP Extensions to install via docker-php-ext-install.

NOTE: use PHP_EXTENSIONS_EXTRA if you want to add additional extensions; only override this if you're going to change the baseline extensions.

See the How to install more PHP extensions documentation on Docker Hub for more information

Default value: intl bcmath zip pcntl exif curl gd

PHP_EXTENSIONS_EXTRA

Named DOCKER_APP_PHP_EXTENSIONS_EXTRA in your .env file

Extra PHP Extensions (separated by space) to install via docker-php-ext-install.

See the How to install more PHP extensions documentation on Docker Hub for more information.

Default value: ""

PHP_EXTENSIONS_DATABASE

PHP database extensions to install.

By default, we install both pgsql and mysql since they're more convenient (and add very little build time! But it can be overwritten here if desired.

Default value: pdo_pgsql pdo_mysql pdo_sqlite

COMPOSER_VERSION

The version of Composer to install.

For valid values, please see the Docker Hub composer page.

Default value: 2.6

APT_PACKAGES_EXTRA

Named DOCKER_APP_APT_PACKAGES_EXTRA in your .env file

Extra APT packages (separated by space) that should be installed inside the image by apt-get install

Default value: ""

NGINX_VERSION

The version of nginx to use when targeting nginx-runtime.

Please see the Docker Hub nginx page for available versions.

Default value: 1.25.3

FOREGO_VERSION

The version of forego to install.

Default value: 0.17.2

GOMPLATE_VERSION

The version of goplate to install.

Default value: v3.11.6

DOTENV_LINTER_VERSION

Version of dotenv-linter to install.

Default value: v3.2.0

PHP_BASE_TYPE

Named DOCKER_APP_BASE_TYPE in your .env file

The PHP base image layer to use when building the runtime container.

When targeting

Valid values:

  • apache
  • cli

Default value: apache

PHP_DEBIAN_RELEASE

Named DOCKER_APP_DEBIAN_RELEASE in your .env file

The Debian Operation System version to use.

Valid values:

  • bookworm

Default value: bookworm