basictheprogram/crossfire-phpbb3 repository overview

⁠Docker image for phpBB3

⁠What is phpBB?

phpBB is a popular open-source bulletin board that features robust messaging capabilities: flat message structure, subforums, topic split/merge/lock, user groups, full-text search, and attachments.

• Upstream: https://www.phpbb.com⁠
• Source: https://github.com/phpbb/phpbb⁠

⁠About this image

This image provides a Docker-based deployment for phpBB3 on Apache with PHP 8.4 (Debian Trixie). It was originally created for the Crossfire Forums but the packaging is general-purpose and not specific to that deployment.

Key differences from the official phpBB distribution:

• Multi-stage build: extensions and PECL packages compiled in a cli builder stage; only runtime libraries copied into the apache final stage
• ImageMagick (via imagick PECL extension) and GD enabled
• opcache tuned for production
• mod_remoteip configured for reverse-proxy deployments

This image does not auto-provision phpBB from environment variables the way some other packaged images do. phpBB is configured through its own web-based installer on first run — see First-time setup⁠.

⁠TL;DR

docker run --name phpbb basictheprogram/crossfire-phpbb3:latest

⁠Prerequisites

Docker Engine 20.10 or later. Docker Compose v2 recommended.

⁠Get this image

Pull from Docker Hub:

docker pull basictheprogram/crossfire-phpbb3:latest

Pull a specific version:

docker pull basictheprogram/crossfire-phpbb3:[TAG]

Tags follow the phpBB3 upstream version. CI publishes:

• latest and <version> (e.g. 3.3.19) on pushes to main
• devel-<version> on pushes to devel
• <commit-sha> on every push

Available tags: https://hub.docker.com/repository/docker/basictheprogram/crossfire-phpbb3/tags⁠

Build locally:

git clone https://github.com/crossfire-projects/docker-phpbb.git
cd docker-phpbb
docker build -t crossfire-phpbb3 php/

⁠How to use this image

phpBB3 requires a MySQL or MariaDB database. Use Docker Compose to run both together:

docker compose up -d

Copy .env.sample⁠ to .env and fill in real values first — compose.yml reads its database and Traefik settings from there.

⁠First-time setup

This image does not auto-provision phpBB from environment variables. On first run, phpBB's own installer is still present in the image; the PHPBB_DATABASE_* values in compose.yml are not read by anything in the image; they're there so you have one place to keep the values consistent with what you type into the installer.

1. docker compose up -d
2. Browse to http://<host>/install/ and complete phpBB's installer (database connection, admin account, forum name, etc.)
3. Once the installer writes config.php (persisted on the phpbb_config volume), the container's entrypoint automatically removes the install/ directory the next time it starts — restart the phpbb container to trigger that
4. SMTP and other forum settings are configured afterward through phpBB's own Admin Control Panel (ACP), not environment variables

⁠Persisting your application

compose.yml already defines named volumes for the database and every phpBB directory that needs to survive a container recreate:

services:
  mysql:
    volumes:
      - phpbb-mysql-data:/var/lib/mysql
  phpbb:
    volumes:
      - phpbb_config:/config-volume       # config.php (DB credentials)
      - phpbb_files:/var/www/html/phpBB3/files
      - phpbb_images:/var/www/html/phpBB3/images
      - phpbb_store:/var/www/html/phpBB3/store
      - phpbb_ext:/var/www/html/phpBB3/ext
      - phpbb_styles_crossfire:/var/www/html/phpBB3/styles/crossfire

Without these volumes, all data is lost when the container is removed.

Note what's not covered: the rest of styles/ (including the stock Prosilver style) isn't persisted, so any change made directly to styles/prosilver/... is lost on the next rebuild — this is what happened in issue #7⁠. For custom branding (a logo, colors, etc.), create a child style that inherits from Prosilver — e.g. one named crossfire — through phpBB's ACP (Customise → Styles → Manage styles), and set it as the default style. Files under a child style's own directory land on the phpbb_styles_crossfire volume and survive upgrades; the stock prosilver style stays upgradable.

⁠Configuration

⁠Environment variables

Only these are actually read by something in this repo. See .env.sample⁠ for the full list with example values.

⁠Logging

Container logs go to stdout:

docker compose logs phpbb

⁠Maintenance

⁠Backup

docker compose stop phpbb
docker run --rm \
  -v /path/to/phpbb-backups:/backups \
  --volumes-from phpbb \
  busybox cp -a /var/www/html/phpBB3 /backups/latest

⁠Upgrade

1. Pull the new image tag
2. Stop the running container
3. Take a backup (see above)
4. Update the image tag in compose.yml
5. docker compose up -d

⁠Extend this image

FROM basictheprogram/crossfire-phpbb3:latest
USER 0
RUN apt-get update && apt-get install -y --no-install-recommends vim \
    && rm -rf /var/lib/apt/lists/*
USER www-data

⁠Third-party software

This image downloads and ships phpBB3, which is distributed under the GNU General Public License, Version 2⁠.

• phpBB3 upstream source: https://github.com/phpbb/phpbb⁠
• phpBB3 license: https://github.com/phpbb/phpbb/blob/master/LICENSE⁠

The GPL v2 requires that the phpBB3 source be made available to recipients of this image. The unmodified phpBB3 source is available at the upstream GitHub repository linked above. This project's own files (Dockerfile, scripts, configuration) are licensed separately under the MIT License — see LICENSE.md⁠.

⁠Author

Bob Tanner⁠, maintained by Rick Tanner⁠.

⁠License

This project's own files (Dockerfile, scripts, configuration) are licensed under the MIT License — see LICENSE.md⁠. phpBB3 itself is distributed separately under GPL v2 — see Third-party software⁠.

⁠Issues

File an issue at https://github.com/crossfire-projects/docker-phpbb/issues⁠.