Install Drupal 9/10 CMS in an AFS-Based Virtual Host

Environment

Drupal 9/10 CMS, AFS virtual host

Issue

How to install Drupal 9/10 CMS in an AFS-based virtual host

IMPORTANT SECURITY NOTE:  Per the Drupal core release cycle, Drupal 9 end-of-life and end of security support was reached on November 1, 2023.  References to Drupal 9 are still retained in this document for now, but no new Drupal sites should be installed based on Drupal 9.x.  Please install new sites based on Drupal 10.  Existing Drupal 9 sites are strongly encouraged to upgrade to Drupal 10 as soon as possible to minimize exposure to any potential security issues with (now unsupported) Drupal 9 in the future.

Resolution

1. Identify the latest Drupal release from https://www.drupal.org/project/drupal/releases and note the release version number (referenced as "{{release}}" below)
2. Establish an SSH session to "login.itd.umich.edu", then run the following command to download and unpack the Drupal release in your Document Root directory
   1. (Substitute your actual directory name for "{{doc_root}}".)

wget -O - 'https://ftp.drupal.org/files/projects/drupal-{{release}}.tar.gz' | tar --strip-components 1 -C {{doc_root}}  -xzf -

​​​​​​Note that recent versions of Drupal have PHP minimum version requirements.  Contact the ITS Web Team if you're concerned about the PHP version for your host (we offer versions 7.3 and 8.1).

3. Once you've downloaded the Drupal software, you'll need to make some changes to permissions
   1. This will let the install.php script edit sites/default/settings.php, with your database info
   2. Since this is AFS, unix permissions mentioned in the Drupal documentation aren't significant
   3. Also, the first time you try uploading an image file, etc., Drupal will try to create sites/default/files, and subdirectories therein
   4. The 'files' directory will likely need to retain write permissions long-term, but sites/default should never have write access (after initial installation) to prevent site security issues

fs sa sites/default umweb:servers write
cp sites/default/default.settings.php sites/default/settings.php
mkdir sites/default/files
fs sa sites/default/files umweb:servers write

4. Install composer into your site
   1. Follow the instructions for downloading and installing composer on the Composer Download site.  You may wish to install composer as vendor/bin/composer in your {{doc_root}}
   2. For example, to download and install composer as {{doc_root}}/vendor/bin/composer, modify the third line of the four line sequence of commands found on the download site as follows (substitute the absolute path of your Drupal Document Root for "{{doc_root}}").  Note that line 2 below has been truncated and is NOT functional as-is.  This is just provided as an example.  You will need to copy the exact line 2 from the download page to get the latest release.

If installed successfully, you should be able to use composer from your {{doc_root}} as follows:

5. Install drush into your site via composer
   1. Install drush based on the installation directions on the drush site
   2. From your Drupal Document Root (referenced above as "{{doc_root}}"):

If installed successfully, you should be able to use drush from your {{doc_root}} as follows:

6. In a web browser, navigate to your site's URL and begin the standard Drupal installation via the web UI

7. For the step "Set up database", enter your database name, username, password, and in `ADVANCED OPTIONS`, make sure you specify the fully qualified domain name (FQDN) of the mySQL database host (eg, webapps-db.web.itd.umich.edu, webapps2-db.miserver.it.umich.edu, etc.) as localhost will not work here
   1. Specify a `Table name prefix` if necessary per your requirements
8. After setting up the DB, you'll see an additional page to set the admin password for your Drupal site along with other details
9. Once that's complete, the sites/default directory must not be left writable so remove the permissions you set for it
   1. Bypassing this step will result in security issues with your installation.

fs sa sites/default umweb:servers read

Generally, our servers should be configured not to execute PHP out of any writable directory.  Please contact us to disable PHP if you leave a location writable after the installation process is finished. 

OpenID Connect (OIDC) authentication for your Drupal site

Assuming SSL and OIDC are to be configured for your Drupal site, you can use the module "openid_connect" to replace Drupal login pages with OIDC.  Please see the Knowledge Artticle: Install and Configure OpenID Connect (OIDC) Client for Drupal 9/10 in an AFS-based Virtual Host for more information.

Keeping Drupal up-to-date

Keep your core Drupal instance up-to-date, along with all installed optional modules and themes.

Additional Information

Need additional information or assistance? Contact the ITS Service Center.