evandarwin/phpbb repository overview

⁠evandarwin/phpbb-docker

Looking for a modern, secure, and hassle-free way to run phpBB in Docker? You've found it! This image offers a thoughtfully pre-configured phpBB environment that's ready for production use with minimal setup.

⁠Why Choose This Image?

After Bitnami/Broadcom deprecated their official phpBB container (which had become outdated), I created this project to give the community a modern alternative that prioritizes:

• Security: Runs as non-root, includes hardened Nginx config, secure headers, and protection against common attacks
• Performance: Pre-configured with PHP opcache, Nginx (instead of Apache), and optimized settings
• Simplicity: Works out-of-the-box with sensible defaults while remaining highly customizable
• Flexibility: Supports MySQL, PostgreSQL, and SQLite with easy configuration
• Currency: Daily builds ensure you always have the latest phpBB version and security patches

⁠Quick Start (It's Really That Easy!)

docker run -d \
  -p 8080:8080 \
  -v phpbb_data:/opt/phpbb \
  -e PHPBB_FORUM_NAME="My Awesome Forum" \
  -e PHPBB_DATABASE_HOST="db" \
  -e PHPBB_DATABASE_NAME="phpbb" \
  -e PHPBB_DATABASE_USER="phpbb" \
  -e PHPBB_DATABASE_PASSWORD="secret" \
  evandarwin/phpbb:latest

Then just open http://localhost:8080⁠ in your browser, and you're ready to go!

⁠Available Tags

• latest - Latest phpBB version with all the good stuff
• <version> - Specific phpBB version (e.g., 3.3.15)
• <major>.<minor> - Latest patch version of a minor release (e.g., 3.3)
• <major> - Latest minor.patch version of a major release (e.g., 3)

All images are built on Alpine Linux for minimal size and maximum security.

⁠Pre-Configured Features You'll Love

This image comes with numerous thoughtful pre-configurations that save you time and enhance security:

⁠🛡️ Security Enhancements

• Defense in Depth: Multiple layers of protection including:
  • Non-root execution with proper file permissions
  • Protection against common web attacks
  • Nginx configuration to protect sensitive files and directories
  • Disabled dangerous PHP functions like exec and shell_exec
  • Open basedir restrictions to limit file access

⁠⚡ Performance Optimizations

• PHP Opcache: Pre-configured for optimal performance
• Nginx: Lightweight and fast web server with optimized settings
• Static File Caching: Properly configured for optimal browser caching
• Tuned PHP Settings: Balanced for good performance while maintaining stability

⁠🧰 Convenience Features

• Auto-configuration: Just set environment variables and go
• Multi-DB Support: Choose MySQL, PostgreSQL, or SQLite based on your needs
• Health Checks: Built-in container health monitoring
• Smart Defaults: Works out-of-the-box, but remains highly customizable

⁠Required Environment Variables

This container requires the following environment variables to be set for proper operation:

• PHPBB_USERNAME: Username for the administrative user (required for first installation)
• PHPBB_PASSWORD: Password for the administrative user (required for first installation)

These variables are mandatory for generating the database during first initialization.

By default, the container uses a SQLite database configuration that is automatically written to the mounted volume at /opt/phpbb/phpbb.sqlite unless you specify a different database configuration. This provides a simple setup with minimal configuration while ensuring your data is properly persisted.

⁠Environment Variables

The following environment variables can be used to configure the phpBB installation:

⁠Forum Configuration

⁠Admin User

⁠Database Configuration

⁠Email / SMTP

⁠HTTP Configuration

⁠PHP Configuration

⁠Data Persistence

There are two main approaches to persist your phpBB data:

⁠1. Simple Volume Mounting (Recommended)

Mount a single volume to keep everything in one place:

docker run -d \
  -p 8080:8080 \
  -v phpbb_data:/opt/phpbb \
  -e PHPBB_FORUM_NAME="My Awesome Forum" \
  -e PHPBB_DATABASE_HOST="db" \
  -e PHPBB_DATABASE_NAME="phpbb" \
  -e PHPBB_DATABASE_USER="phpbb" \
  -e PHPBB_DATABASE_PASSWORD="secret" \
  evandarwin/phpbb:latest

⁠2. Granular Control with Multiple Volumes

For more control over specific data directories:

docker run -d \
  -p 8080:8080 \
  -v phpbb_config:/opt/phpbb/config \
  -v phpbb_store:/opt/phpbb/store \
  -v phpbb_files:/opt/phpbb/files \
  -v phpbb_images:/opt/phpbb/images \
  -v phpbb_ext:/opt/phpbb/ext \
  -e PHPBB_DATABASE_HOST="db" \
  -e PHPBB_DATABASE_NAME="phpbb" \
  -e PHPBB_DATABASE_USER="phpbb" \
  -e PHPBB_DATABASE_PASSWORD="secret" \
  evandarwin/phpbb:latest

⁠Custom PHP Configuration

You can customize your PHP settings by providing PHP.ini directives through the PHP_CUSTOM_INI environment variable:

docker run -d \
  -p 8080:8080 \
  -v phpbb_data:/opt/phpbb \
  -e PHPBB_FORUM_NAME="My Community" \
  -e PHPBB_DATABASE_HOST="mysql_container" \
  -e PHPBB_DATABASE_NAME="phpbb_db" \
  -e PHPBB_DATABASE_USER="phpbb_user" \
  -e PHPBB_DATABASE_PASSWORD="secure_password" \
  -e PHP_CUSTOM_INI="upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M
max_execution_time = 60" \
  evandarwin/phpbb:latest

These directives will be appended to the PHP.ini file during container startup.

⁠Real-World Examples

⁠MySQL Setup (Most Common)

docker run -d \
  -p 8080:8080 \
  -v phpbb_data:/opt/phpbb \
  -e PHPBB_FORUM_NAME="My Community" \
  -e PHPBB_DATABASE_DRIVER="mysqli" \
  -e PHPBB_DATABASE_HOST="mysql_container" \
  -e PHPBB_DATABASE_NAME="phpbb_db" \
  -e PHPBB_DATABASE_USER="phpbb_user" \
  -e PHPBB_DATABASE_PASSWORD="secure_password" \
  evandarwin/phpbb:latest

⁠PostgreSQL Setup

docker run -d \
  -p 8080:8080 \
  -v phpbb_data:/opt/phpbb \
  -e PHPBB_FORUM_NAME="My Community" \
  -e PHPBB_DATABASE_DRIVER="postgres" \
  -e PHPBB_DATABASE_HOST="postgres_container" \
  -e PHPBB_DATABASE_NAME="phpbb_db" \
  -e PHPBB_DATABASE_USER="phpbb_user" \
  -e PHPBB_DATABASE_PASSWORD="secure_password" \
  evandarwin/phpbb:latest

⁠SQLite Setup (Great for Small Forums)

docker run -d \
  -p 8080:8080 \
  -e PHPBB_FORUM_NAME="My Community" \
  -e PHPBB_DATABASE_DRIVER="sqlite3" \
  -e PHPBB_DATABASE_SQLITE_PATH="/opt/phpbb/data/phpbb.sqlite3" \
  -v phpbb_data:/opt/phpbb \
  evandarwin/phpbb:latest

⁠Complete Setup with Email

docker run -d \
  -p 8080:8080 \
  -v phpbb_data:/opt/phpbb \
  -e PHPBB_FORUM_NAME="My Community" \
  -e PHPBB_EMAIL="[email protected]" \
  -e SMTP_HOST="smtp.example.com" \
  -e SMTP_PORT="587" \
  -e SMTP_USER="smtp_user" \
  -e SMTP_PASSWORD="smtp_password" \
  -e PHPBB_DATABASE_HOST="mysql_container" \
  -e PHPBB_DATABASE_NAME="phpbb_db" \
  -e PHPBB_DATABASE_USER="phpbb_user" \
  -e PHPBB_DATABASE_PASSWORD="secure_password" \
  evandarwin/phpbb:latest

⁠Building Your Own Images

You can build your own phpBB Docker images using the provided build script:

# Build the latest phpBB with PHP 8.4
./scripts/build.sh

# Build a specific phpBB version
PHPBB_VERSION=3.3.10 ./scripts/build.sh

The build script automatically fetches the latest phpBB release version from GitHub if you don't specify a version.

⁠Docker Compose Example (Production-Ready)

Here's a complete example using Docker Compose with MySQL:

version: '3.8'

services:
  phpbb:
    image: evandarwin/phpbb:latest
    ports:
      - '8080:8080'
    environment:
      - PHPBB_FORUM_NAME=My Amazing Forum
      - PHPBB_FORUM_DESCRIPTION=Welcome to my phpBB forum
      - PHPBB_USERNAME=admin
      - PHPBB_PASSWORD=secure_password
      - [email protected]
      - PHPBB_DATABASE_DRIVER=mysqli
      - PHPBB_DATABASE_HOST=mysql
      - PHPBB_DATABASE_NAME=phpbb
      - PHPBB_DATABASE_USER=phpbb
      - PHPBB_DATABASE_PASSWORD=mysql_password
      - SERVER_NAME=forums.example.com
      - COOKIE_SECURE=false
    volumes:
      - phpbb_data:/opt/phpbb
    depends_on:
      - mysql
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:8080/']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=phpbb
      - MYSQL_USER=phpbb
      - MYSQL_PASSWORD=mysql_password
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped
    healthcheck:
      test:
        ['CMD', 'mysqladmin', 'ping', '-h', 'localhost', '-u', 'root', '-p${MYSQL_ROOT_PASSWORD}']
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

volumes:
  phpbb_data:
  mysql_data:

For PostgreSQL, replace the MySQL service with:

postgres:
  image: postgres:15
  environment:
    - POSTGRES_PASSWORD=postgres_password
    - POSTGRES_USER=phpbb
    - POSTGRES_DB=phpbb
  volumes:
    - postgres_data:/var/lib/postgresql/data
  restart: unless-stopped
  healthcheck:
    test: ['CMD', 'pg_isready', '-U', 'phpbb']
    interval: 10s
    timeout: 5s
    retries: 3
    start_period: 30s

⁠Using Behind a Reverse Proxy

When using this container behind a reverse proxy like Traefik or Nginx:

1. Set the SERVER_NAME to your domain name
2. Set SERVER_PROTOCOL to https:// if using SSL/TLS
3. Set COOKIE_SECURE=true for secure cookies

Example Docker Compose configuration with Traefik:

services:
  phpbb:
    image: evandarwin/phpbb:latest
    environment:
      - SERVER_NAME=forums.example.com
      - SERVER_PROTOCOL=https://
      - COOKIE_SECURE=true
      # Other configuration...
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.phpbb.rule=Host(`forums.example.com`)'
      - 'traefik.http.routers.phpbb.entrypoints=websecure'
      - 'traefik.http.routers.phpbb.tls=true'

⁠Security Best Practices

This Docker image implements numerous security best practices:

• Non-root execution: All processes run as a non-privileged user
• Security headers: Comprehensive set of headers to protect against XSS, clickjacking, and more
• Protected sensitive files: Nginx blocks access to configuration and system files
• PHP hardening: Restricted functions, open_basedir limitations, and proper error handling
• Secure default settings: Sensible security defaults that don't sacrifice usability

⁠SQLite Database Security

⁠IMPORTANT: Secure Storage of SQLite Databases

When using SQLite as your database driver, it's critically important to store your database file outside of the publicly accessible web directory.

The launcher script will reject it by default if it detects it; but... you know users. We also make a best effort to prevent distributing files with database extensions at all, denied through the nginx configuration (.sql, .db, et al).

⁠Security Risks

Storing SQLite database files in publicly accessible locations presents severe security risks:

• Data Theft: If an attacker can directly download your .sqlite or .db file, they gain access to all forum data including user credentials
• Data Manipulation: Unauthorized modification of your database could lead to account takeovers
• Privacy Violations: Personal user information could be exposed, potentially violating privacy laws

⁠Recommendations

1. Store your SQLite database in a directory that is:

   • NOT accessible from the web
   • NOT inside the /opt/phpbb public directory structure
   • Properly permission-restricted

2. When using the PHPBB_DATABASE_SQLITE_PATH environment variable:

   • Use a path like /var/lib/phpbb/data/phpbb.sqlite3
   • NEVER use a path within the phpBB root directory
   • The container is configured to reject SQLite paths that contain the phpBB root directory

3. Use volume mounting to persist your SQLite database:

docker run -d \
  -p 8080:8080 \
  -e PHPBB_FORUM_NAME="My Community" \
  -e PHPBB_DATABASE_DRIVER="sqlite3" \
  -e PHPBB_DATABASE_SQLITE_PATH="/var/lib/phpbb/data/phpbb.sqlite3" \
  -v phpbb_sqlite_data:/var/lib/phpbb/data \
  -v phpbb_data:/opt/phpbb \
  evandarwin/phpbb:latest

⁠Additional Protection

The nginx configuration in this container will automatically block access to any .sqlite or .db files, but this should be considered a last line of defense rather than your primary security measure.

⁠Container Health Monitoring

This Docker image includes a built-in health check that verifies the web server is responding properly. The health check:

• Runs every 30 seconds after a 30-second startup period
• Verifies that the Nginx web server is running and responding to HTTP requests
• Will automatically mark the container as unhealthy if the web server stops responding

This is particularly useful when using the container with orchestration systems like Docker Swarm, Kubernetes, or Docker Compose with health checks.

⁠Troubleshooting Tips

⁠Common Issues and Solutions

1. Database Connection Errors:

   • Double-check your database credentials and connection settings
   • Verify network connectivity between containers
   • For MySQL, ensure the user has proper privileges

2. Permission Issues:

   • If mounting volumes, ensure they have the correct ownership and permissions
   • The container uses a non-root user with UID/GID different from the host

3. PHP Configuration:

   • If you need to adjust PHP settings beyond what's available through environment variables, you can mount a custom php.ini file

4. Nginx Logs:

   • Container logs include nginx access and error logs
   • You can view them with docker logs <container_name>

⁠Accessing Logs

All logs are forwarded to the Docker logging system:

# View all logs
docker logs <container_name>

# View only recent logs
docker logs --tail 100 <container_name>

# Follow logs in real-time
docker logs -f <container_name>

⁠Need Help or Want to Contribute?

Contributions are always welcome! Whether it's reporting bugs, suggesting features, or submitting pull requests, your input helps make this project better for everyone.

If you're using this image in production, I'd love to hear about your experience!