Full update between different PHPBB versions

Dockerfile

@@ -80,6 +80,7 @@ RUN apk update && \
     apk add --no-cache \
     nginx \
     curl \
+    rsync \
     unzip \
     libcap \
     ca-certificates \
@@ -121,7 +122,7 @@ RUN sed -i "s/user = nobody/user = phpbb/g" /etc/php${PHP_VERSION}/php-fpm.d/www
     chown phpbb:phpbb /run/nginx.pid
 
 # Copy scripts and configurations
-COPY scripts/install-phpbb.sh scripts/docker-entrypoint.sh scripts/install-from-yml.sh /opt/.docker/
+COPY scripts/install-phpbb.sh scripts/docker-entrypoint.sh scripts/install-from-yml.sh scripts/update-db-migration.sh /opt/.docker/
 COPY config/nginx.conf /etc/nginx/http.d/default.conf
 
 # Download and install phpBB during the build
@@ -145,15 +146,16 @@ RUN if [ -z "${PHPBB_VERSION}" ]; then \
     mkdir -p ${PHPBB_ROOT}/phpbb && \
     mv "phpBB3"/* ${PHPBB_ROOT}/phpbb/ && \
     rm -rf "phpBB3" && \
-    mkdir -p ${PHPBB_ROOT}/phpbb/config && \
+    mkdir -p ${PHPBB_ROOT}/config && \
     touch ${PHPBB_ROOT}/phpbb/config/config.php && \
     chown -R phpbb:phpbb ${PHPBB_ROOT} && \
     # Set base permissions
     chmod -v 0750 ${PHPBB_ROOT} ${PHPBB_ROOT}/phpbb ${PHPBB_ROOT}/phpbb/* && \
     mkdir -p ${PHPBB_ROOT}/phpbb/images/avatars/uploads && \
     # Set writable directory permissions
     chmod -v 0770 ${PHPBB_ROOT}/phpbb/store ${PHPBB_ROOT}/phpbb/cache ${PHPBB_ROOT}/phpbb/files ${PHPBB_ROOT}/phpbb/images/avatars/uploads/ && \
-    chmod 0640 ${PHPBB_ROOT}/phpbb/config/config.php && \
+    chmod -v 0750 ${PHPBB_ROOT}/config && \
+    chmod -v 0640 ${PHPBB_ROOT}/phpbb/config/config.php && \
     # Set subdirectory permissions
     find ${PHPBB_ROOT}/phpbb/cache -type d -exec chmod 750 {} \; && \
     find ${PHPBB_ROOT}/phpbb/store -type d -exec chmod 750 {} \; 2>/dev/null || true && \
@@ -190,4 +192,4 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
 USER phpbb
 
 ENTRYPOINT ["/opt/.docker/docker-entrypoint.sh"]
-CMD ["nginx", "-g", "daemon off;"]
+CMD ["nginx", "-g", "daemon off;"]

README.md

@@ -100,7 +100,9 @@ persisted.
 
 ## Environment Variables
 
-The following environment variables can be used to configure the phpBB installation:
+The following environment variables can be used to configure the initial phpBB installation.
+Note that only the PHP configuration variables have any effect if you already have
+an existing `config.php` (with database connection information) and database from a previous installation.
 
 ### Forum Configuration
 
@@ -166,7 +168,7 @@ The following environment variables can be used to configure the phpBB installat
 
 There are two main approaches to persist your phpBB data:
 
-### 1. Simple Volume Mounting (Recommended)
+### 1. Simple Volume Mounting
 
 Mount a single volume to keep everything in one place:
 
@@ -182,24 +184,44 @@ docker run -d \
   evandarwin/phpbb:latest
 ```
 
-### 2. Granular Control with Multiple Volumes
+### 2. Granular Control with Multiple Volumes (Upgrade Path)
 
 For more control over specific data directories:
 
 ```bash
 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 \
+  -v phpbb_store:/opt/phpbb/phpbb/store \
+  -v phpbb_files:/opt/phpbb/phpbb/files \
+  -v phpbb_images:/opt/phpbb/phpbb/images \
+  -v phpbb_ext:/opt/phpbb/phpbb/ext \
+  -v phpbb_style:/opt/phpbb/phpbb/styles \
   -e PHPBB_DATABASE_HOST="db" \
   -e PHPBB_DATABASE_NAME="phpbb" \
   -e PHPBB_DATABASE_USER="phpbb" \
   -e PHPBB_DATABASE_PASSWORD="secret" \
   evandarwin/phpbb:latest
 ```
+Here, the /opt/phpbb/config directory is used to persist the `config.php` file only, it is copied to/from there during container startup/installation.
+The `store`, `files` and `images` folders should be persisted; adding `ext` and `styles` folders gives you the option to install custom extensions and styles.
+
+The `config.php` needs to be a local file with initial write permissions for the first setup.
+The write permissions need to be for the phpbb user in the container, likely UID 100, GUID 101, see also [Issue #3](https://github.com/EvanDarwin/phpbb-docker/issues/3).
+Once the initial installation ran and setup created the database tables and `config.php`, the `config` folder can also be mounted read-only:
+```bash
+docker ... -v phpbb_config:/opt/phpbb/config:ro ...
+```
+
+If you have (a backup of) an existing installation with database and config.php, you can restore these folders and the database from the backup.
+
+## Upgrade path
+If you mount the full `/opt/phpbb` folder persistently (option 1 above), the docker container will not upgrade to new versions correctly (at least as of now), since the volume mount hides the updated forum files of the container.
+
+However, if you choose option 2 to mount only the `config.php` and folders `store`, `files` and `images` persistently, and optionally `ext` and `styles`,
+then upgrading the docker volume is equivalent to a [full upgrade](https://www.phpbb.com/support/docs/en/3.3/ug/upgradeguide/update_full/).
+
+In that case, the container is setup to automatically perform database migrations as well on startup.
 
 ## Custom PHP Configuration
 
@@ -307,28 +329,44 @@ specify a version.
 Here's a complete example using Docker Compose with MySQL:
 
 ```yaml
-version: '3.8'
+volumes:
+  phpbb_config:
+  phpbb_files:
+  phpbb_store:
+  phpbb_images:
+  phpbb_ext:
+  phpbb_styles:
+  mysql_data:
+
+networks:
+  phpbb-net:
+    driver: bridge
 
 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
-      - PHPBB_EMAIL=admin@example.com
-      - 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
+      PHPBB_FORUM_NAME: My Amazing Forum
+      PHPBB_FORUM_DESCRIPTION: Welcome to my phpBB forum
+      PHPBB_USERNAME: admin
+      PHPBB_PASSWORD: secure_password # <- CHANGE THIS!
+      PHPBB_EMAIL: admin@example.com
+      PHPBB_DATABASE_DRIVER: mysqli
+      PHPBB_DATABASE_HOST: mysql
+      PHPBB_DATABASE_NAME: phpbb
+      PHPBB_DATABASE_USER: phpbb
+      PHPBB_DATABASE_PASSWORD: mysql_password # <- CHANGE THIS!
+      SERVER_NAME: forums.example.com
+      COOKIE_SECURE: false
     volumes:
-      - phpbb_data:/opt/phpbb
+      - phpbb_config:/opt/phpbb/config  # other path: no typo! should only contain config.php
+      - phpbb_files:/opt/phpbb/phpbb/files
+      - phpbb_store:/opt/phpbb/phpbb/store
+      - phpbb_images:/opt/phpbb/phpbb/images
+      - phpbb_ext:/opt/phpbb/phpbb/ext  # optional
+      - phpbb_styles:/opt/phpbb/phpbb/styles  # optional
     depends_on:
       - mysql
     restart: unless-stopped
@@ -338,28 +376,21 @@ services:
       timeout: 5s
       retries: 3
       start_period: 30s
+    networks:
+      - phpbb-net
 
   mysql:
-    image: mysql:8.0
+    image: mariadb:latest
     environment:
-      - MYSQL_ROOT_PASSWORD=root_password
-      - MYSQL_DATABASE=phpbb
-      - MYSQL_USER=phpbb
-      - MYSQL_PASSWORD=mysql_password
+      MARIADB_RANDOM_ROOT_PASSWORD: yes
+      MARIADB_DATABASE: phpbb
+      MARIADB_USER: phpbb
+      MARIADB_PASSWORD: mysql_password # <- CHANGE THIS!
     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:
+    networks:
+      - phpbb-net
 ```
 
 For PostgreSQL, replace the MySQL service with:
@@ -368,9 +399,9 @@ For PostgreSQL, replace the MySQL service with:
 postgres:
   image: postgres:15
   environment:
-    - POSTGRES_PASSWORD=postgres_password
-    - POSTGRES_USER=phpbb
-    - POSTGRES_DB=phpbb
+    POSTGRES_PASSWORD: postgres_password
+    POSTGRES_USER: phpbb
+    POSTGRES_DB: phpbb
   volumes:
     - postgres_data:/var/lib/postgresql/data
   restart: unless-stopped
@@ -497,7 +528,9 @@ Kubernetes, or Docker Compose with health checks.
 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
+   - The container uses a non-root user with UID/GID different from the host, by default 100/101.
+   - Docker populates *empty* volumes (but not mounts!) with the pre-existing folders.
+   - Use a different entrypoint, e.g. `docker compose run --entrypoint sh -it phpbb` to trouble-shoot permissions in the volumes.
 
 3. **PHP Configuration**:
 

docker-compose.yml

@@ -0,0 +1,63 @@
+volumes:
+  phpbb_config:
+  phpbb_files:
+  phpbb_store:
+  phpbb_images:
+  phpbb_ext:
+  phpbb_styles:
+  mysql_data:
+
+networks:
+  phpbb-net:
+    driver: bridge
+
+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 # <- CHANGE THIS!
+      PHPBB_EMAIL: admin@example.com
+      PHPBB_DATABASE_DRIVER: mysqli
+      PHPBB_DATABASE_HOST: mysql
+      PHPBB_DATABASE_NAME: phpbb
+      PHPBB_DATABASE_USER: phpbb
+      PHPBB_DATABASE_PASSWORD: mysql_password # <- CHANGE THIS!
+      SERVER_NAME: forums.example.com
+      COOKIE_SECURE: false
+    volumes:
+      - phpbb_config:/opt/phpbb/config  # other path: no typo! should only contain config.php
+      - phpbb_files:/opt/phpbb/phpbb/files
+      - phpbb_store:/opt/phpbb/phpbb/store
+      - phpbb_images:/opt/phpbb/phpbb/images
+      - phpbb_ext:/opt/phpbb/phpbb/ext  # optional
+      - phpbb_styles:/opt/phpbb/phpbb/styles  # optional
+    depends_on:
+      - mysql
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:8080/']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    networks:
+      - phpbb-net
+
+  mysql:
+    image: mariadb:latest
+    environment:
+      MARIADB_RANDOM_ROOT_PASSWORD: yes
+      MARIADB_DATABASE: phpbb
+      MARIADB_USER: phpbb
+      MARIADB_PASSWORD: mysql_password # <- CHANGE THIS!
+    volumes:
+      - mysql_data:/var/lib/mysql
+    restart: unless-stopped
+    networks:
+      - phpbb-net
+

scripts/build.sh

@@ -101,5 +101,5 @@ log "==> Build complete!"
 
 # Display success message
 log "==> All builds complete!"
-log "To run the container: docker run -p 80:80 $DOCKER_IMAGE:<tag>"
-log "Available tags: $VERSION, $MINOR_VERSION, $MAJOR_VERSION, latest"
+log "To run the container: docker run -p 8080:8080 $DOCKER_IMAGE:<tag>"
+log "Available tags: $VERSION, $MINOR_VERSION, $MAJOR_VERSION, latest"