Overview
This website was running Drupal 7 for many, many years (something like 7-9 years). There are many reasons to upgrade: new features, security updates, supporting modern web conventions, compliance, etc. I've put it off for so long because it has worked, the site is fairly well boxed in (from outside access) and because upgrading or maintaining Drupal is very difficult (especially since packages were removed from Debian).
Strategy
I will be using PHP's composer. This is, unfortunately, outside of Debian's package management system. For this reason everything will be installed in /opt.
Reference:
https://www.drupal.org/docs/upgrading-drupal/upgrading-from-drupal-6-or-drupal-7/upgrade-using-web-browser
https://www.bacancytechnology.com/blog/upgrade-drupal-7-to-drupal-8
1. DATABASE PREP
The drupal database (postgres) looks like this:
old_db | postgres | UTF8 | en_US.UTF-8 | en_US.UTF-8 |
The new database (also postgres) will look like this:
new_db | new_user | UTF8 | en_US.UTF-8 | en_US.UTF-8 |
Create the database from the command line:
su postgres
createdb --encoding=UNICODE --owner=new_user new_db
Run pgsql and run this SQL statement:
ALTER DATABASE "new_db" SET bytea_output = 'escape';
2. DRUPAL 8 INSTALL
Drupal 8 will be installed side by side with Drupal 7 (although I will make no attempt to keep Drupal 7 operational).
Put the Drupal 7 install into maintenance mode.
Install Drupal 8 using composer:
mkdir install_dir
mkdir install_dir/8
composer require drush/drush:^8
composer create-project drupal/recommended-project:8.9.20 "install_dir/8"
chown -R www-data.www-data install_dir/8
Be sure to set dir/file ownership to the apache user and group.
Reference:
https://www.drupal.org/docs/8/install
https://www.drush.org/13.x/install/
3. APACHE SETUP
From the web admin interface: save a copy of the Drupal 7 installation's installed modules. You will need this later.
I just reused the Drupal 7 config file. I did not see much info on the web and fortunately this worked.
The web root should point to the directory with index.php.
cp /etc/apache2/sites-available/drupal7.conf /etc/apache2/sites-available/drupal8.conf
edit file...
a2ensite drupal8
systemctl restart apache2
4. MEDIA SETUP
My media is already stored in a single location. This will link the static content to www.teramari.su/files/:
ln -s media_dir/files/ install_dir/8/web/files
5. DRUPAL 8 SETUP
From a browser open your website URL. You should be presented with a setup screen. Create an admin user. It is important to use 'administrator' as this account.
This could result in a broken install. Run this to fix:
cd install_dir/vendor/bin
./drush cr
Then run second time:
./drush cr
This will fix the site (pages can be served, etc) but you may not be able to browse to the admin page or login.
Just clear browser cookies to fix this.
Then, browse to www.teramari.us/admin/reports/status and clear the errors (they seem to vary between install attempts).
6. MIGRATE+UPGRADE DRUPAL 7 TO NEW DRUPAL 8 INSTALLATION
Go through Drupal 7 modules list and install the missing modules. I was more successful leaving out external modules and just enabling modules that were already preinstalled. Make sure they are installed AND enabled.
Drupal 7 modules list:
Aggregator
Block
*Blog (disabled, never used in Drupal 7)
Book
Color
Comment
Contact
*Content translation (?)
Contextual links
*Dashboard (skipped)
Database logging
Field
*Field SQL storage (removed from drupal starting with 8)
Field UI
Filter
*Forum (disabled, never used in drupal 7)
Help
*Menu (renamed to menu UI)
Node
*Overlay (removed from drupal starting with 8)
Path
*PHP filter (removed from drupal starting with 8)
RDF
Search
Shortcut
Statistics
Syslog
System
Taxonomy
*Testing (skipped, never used in drupal 7)
Toolbar
*Tracker (renamed to activity tracker in drupal 8)
Update manager
User
Views
Views UI
File
Image
*List (removed from drupal starting with 8)
*Number (removed from drupal starting with 8)
Options
Text
*Locale (skipped, renamed to several things in drupal 8)
*OpenID (skipped, never used in drupal 7)
*Poll (skipped, never used in drupal 7)
*Trigger (skipped, never used in drupal 7, removed and replaced with rules)
*Chaos tools (skipped, fyi the modules presented between versions seems to have changed)
*CAPTCHA (skipped, will install later)
*reCAPTCHA (skipped, will install later)
Then from a browser run the upgrade script:
www.teramari.us/upgrade
Look at results page for failures. Review log for issues.
Finally, clean out migration garbage from database:
cd install_dir/8/vendor/bin
./drush --root=install_dir/8/web sqlq '\dt migrate_*' | awk '{ print $2 }' | while read TABLE ; do
echo "Dropping $TABLE" && ./drush sqlq "DROP TABLE $TABLE"
done
Reference:
https://www.drupal.org/project/project_module
7. TEST
Write up the upgrade notes (this doc) as a blog post. It should post with no errors.
Post Upgrade
There will be no customization of this site because I plan to immediately upgrade to Drupal 9.
Planning
Upgrades to Drupal 10 and Drupal 11 will come in 2026 along with an upgrade to Debian 12 and Debian 13.