I spent the last days with getting the forum of my Linux distribution updated.

It’s a phpBB forum which was created aeons ago.

In order to investigate the steps needed to upgrade, I simulated the environment in a VirtualBox managed using Vagrant. I know, that all the rage now is about Docker, but that didn’t clicked with me. So I use something I feel comfortable with.

Since I’ve learnt how the deployment works, I am afraid, I can’t merge my changes into the main repository. So for reference here is how to run phpBB with Vagrant

# -*- mode: ruby -*-
# vi: set ft=ruby :

installPath = "scripts/install.sh"

Vagrant.configure("2") do |config|
  # Every Vagrant development environment requires a box. You can search for
  # boxes at https://vagrantcloud.com/search.
  config.vm.box = "ubuntu/xenial64"

  # Create a forwarded port mapping which allows access to a specific port
  # within the machine from a port on the host machine and only allow access
  # via 127.0.0.1 to disable public access
  config.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: "127.0.0.1"

  # Share an additional folder to the guest VM.
  # The first argument is the path on the host to the actual folder.
  # The second argument is the path on the guest to mount the folder.
  # And the optional third argument is a set of non-required options.
  config.vm.synced_folder "./src/", "/tmp/html"
  config.vm.synced_folder "./scripts/", "/tmp/scripts"

  if File.exists? installPath then
    config.vm.provision "shell", path: installPath
  end
end

The associated shell script looks like this:

#!/bin/sh
# Provisions the VM

apt-get -qq update
apt-get -qq install -y apache2 php postgresql postgresql-client unzip libapache2-mod-php7.0 php-xml

HTML_DOCUMENT_ROOT="/var/www/html"
PHPBB_ROOT_PATH="$HTML_DOCUMENT_ROOT/phpBB3"

DOWNLOAD_URL="https://download.phpbb.com/pub/release/3.0/3.0.14/phpBB-3.0.14.zip"
ZIP_FILE="`basename $DOWNLOAD_URL`"
INSTALLATION_PATH="/tmp"

# Download into a clean directory
cd "$INSTALLATION_PATH"
rm -rf "$INSTALLATION_PATH/phpBB*"
rm -rf "$PHPBB_ROOT_PATH"
wget -q "$DOWNLOAD_URL"

echo "Download complete. Copying files to target destination."
unzip -q -o "$ZIP_FILE" -d "$INSTALLATION_PATH"

cp -r "$INSTALLATION_PATH/phpBB3" "$HTML_DOCUMENT_ROOT"
# This should work, but fails for some reason
#id -u php &> /dev/null || adduser --disabled-password --gecos "" php
adduser --disabled-password --gecos "" php
chmod 666 "$PHPBB_ROOT_PATH/config.php"
chmod 777 "$PHPBB_ROOT_PATH/cache/"
chmod 777 "$PHPBB_ROOT_PATH/files/"
chmod 777 "$PHPBB_ROOT_PATH/store/"
chmod 777 "$PHPBB_ROOT_PATH/images/avatars/upload/"
chown -R php "$PHPBB_ROOT_PATH/"

echo "Files copied. Preparing database."
sed -i.bak s/peer/trust/g /etc/postgresql/9.5/main/pg_hba.conf
sudo -u postgres dropdb --if-exists forum
sudo -u postgres dropuser php
sudo -u postgres createuser -d -s php
sudo -u postgres createdb -O php forum

echo "Database ready. Restarting services in order to make changes take effect."
service apache2 reload
service postgresql restart

echo "You can visit http://127.0.0.1:8080/phpBB3/ now."
echo "After installation log into the VM and execute."
echo "sudo su -"
echo "cd /tmp"
echo "./scripts/after-install.sh"

As stated, this starts an Apache webserver, which can be reached on port 8080. The after-install script copies over our custom forums’ changes. This should be done after using the Web UI to complete the installation. I went for weak values:

  • server hostname: localhost
  • server port: leave blank
  • database name: forum
  • database user: php
  • database password: leave blank

Admin setup:

  • username: admin
  • password: secret
  • email: webmaster@forum.php

It’s a throwaway development environment after all… Suffice to say that you should fix the file permissions after an upgrade :-)

In case you want to upgrade to 3.2 here are the steps needed:

#!/bin/sh
# Upgrades existing forum to latest version of 3.2 line

HTML_DOCUMENT_ROOT="/var/www/html"
PHPBB_ROOT_PATH="$HTML_DOCUMENT_ROOT/phpbb3"
BACKUP_ROOT_PATH="$HTML_DOCUMENT_ROOT/forum-backup"

DOWNLOAD_URL="https://www.phpbb.com/files/release/phpBB-3.2.2.zip"
ZIP_FILE="`basename $DOWNLOAD_URL`"
INSTALLATION_PATH="/tmp/"

# Download into a clean directory
cd "$INSTALLATION_PATH"
rm -rf "$INSTALLATION_PATH/phpBB*"
wget -q "$DOWNLOAD_URL"

echo "Download complete. Unpacking and preparing system for upgrade."
unzip -q -o "$ZIP_FILE" -d "$INSTALLATION_PATH"

# Follow download instructions
# c.f. https://www.phpbb.com/support/docs/en/3.0/kb/article/how-to-update-to-the-latest-version-of-phpbb3/
rm "$INSTALLATION_PATH/phpBB3/config.php"
rm -rf "$INSTALLATION_PATH/phpBB3/images"
rm -rf "$INSTALLATION_PATH/phpBB3/files"
rm -rf "$INSTALLATION_PATH/phpBB3/store"

# Instead of deciding what to keep, move everything to another place and restore
rm -rf "$BACKUP_ROOT_PATH"
mv "$PHPBB_ROOT_PATH" "$BACKUP_ROOT_PATH"
mkdir -p "$PHPBB_ROOT_PATH"
mkdir -p "$PHPBB_ROOT_PATH/images/avatars/"

# Restore what's needed for an upgrade
cp "$BACKUP_ROOT_PATH/config.php" "$PHPBB_ROOT_PATH"
cp -rf "$BACKUP_ROOT_PATH/images" "$PHPBB_ROOT_PATH"
cp -rf "$BACKUP_ROOT_PATH/files" "$PHPBB_ROOT_PATH"
cp -rf "$BACKUP_ROOT_PATH/store" "$PHPBB_ROOT_PATH"
cp -rf "$BACKUP_ROOT_PATH/images/avatars/upload" "$PHPBB_ROOT_PATH/images/avatars/"

# Copy files for update from download
cp -rf "$INSTALLATION_PATH/phpBB3/*" "$PHPBB_ROOT_PATH"
mkdir -p "$PHPBB_ROOT_PATH/cache"

# Set file and directory permissions
chown -R php:php "$PHPBB_ROOT_PATH"
chmod 777 "$PHPBB_ROOT_PATH/config.php"
chmod 777 "$PHPBB_ROOT_PATH/cache/"
chmod 777 "$PHPBB_ROOT_PATH/files/"
chmod 777 "$PHPBB_ROOT_PATH/store/"

echo "Please patch fix_user_styles.php line 42 before running the upgrade."
echo "See upgrade-to-3.2.sh for details"
echo "After upgrade restore the file permissions."
# See https://www.phpbb.com/community/viewtopic.php?p=14902921#p14902921
# Patch $PHPBB_ROOT_PATH/phpbb/db/migration/data/v32x/fix_user_styles.php:42
#
# BROKEN:
# $enabled_styles = $result->fetch_array();
# FIXED:
# $enabled_styles = $this->db->sql_fetchrowset($result);

Pay special attention to an error message like

The installer detected a timeout

The installer has detected a timeout, you may try to refresh the page, which may lead to data corruption. We suggest that you either increase your timeout settings or try to use the CLI.

If that is the case, patch line 42 of fix_user_styles.php as described by a phpBB developer.