This section contains guides to help you with installing a new copy of Drupal.  Information on updating and upgrading existing Drupal sites can be found elsewhere in the handbook.

Moving an existing Drupal site (either a production site or one built on a development server) to an OIT Web Hosting account is not terribly difficult, but it is important to make sure you follow all of the right steps.

Skills Required for Migrating a Drupal Site

• You will need to know how to access the Plesk control panel for your account in order to complete the rest of these steps you may also wish to set an SSH password or SSH key so that you can SSH into your web hosting space.
• You should have a basic understanding of filesystems and mySQL databases, as well as phpMyAdmin
• If you need assistance with some of these steps, check with your local unit's IT support staff 

Before You Begin

If you haven't done so already, you'll need to request a hosting account from OIT.  If you are moving a live site, you should ask for the account to be set up as the hostname of your live site, but ask that DNS not be updated yet, since that would disrupt your existing site.  Once the account is set up, you can do one of two things to access it while you are working on migrating your existing site:

1. You can edit your local computer's hosts list (on Linux and Macintosh computers, this is /etc/hosts) to locally map your live site's hostname to your OIT hosting account.  This is the quickest method, but while you have this mapping in place you won't be able access your existing live site from that computer.
2. You can create a DNS alias for your new site.  You or someone in your IT staff will have to create the alias in DNS, and then you'll have to go into the Plesk control panel for your new OIT Web Hosting site and add the alias there (via the Add New Domain Alias button on the main page) so that the Plesk server knows that your DNS alias goes with your OIT Web Hosting account.  This method takes a little more effort to set up, but with it you can access your new site from anywhere while you are testing it, and you can access your existing live site from the same computer at the same time.
3. You could actually mix these two methods for perhaps the most versatile option:  you can define an alias for your new site in your local computer's host file, and then add that alias to your Web Hosting account via the Plesk control panel, but without adding the alias to DNS.  This will let you access both the old and new sites from your local computer, but you still won't be able to access your new site from anywhere else.

When your new site is ready to go live and replace your existing live site, you can have DNS updated (see below) and remove any unneeded aliases that you have created.

Moving Any Drupal Site to an OIT Web Hosting Account

1. You will need to create an archive of the filesystem of your existing site, and an archive (often called an SQL dump) of your existing site's database.  How you do this will depend on where your existing site is located.  Please note that if you are comfortable with using SSH, you can archive your site's filesystem as either a GZipped Tar archive (.tar.gz extension) or a Windows style ZIP archive (.zip extension).  If you are not comofrtable with SSH and prefer to upload your archive to your Web Hosting account via the Plesk control panel, your archive must be in Windows style ZIP format.
2. Upload the archive file to your OIT Web Hosting Account and unpack it where you want your Drupal installation to live.  From within the Plesk control panel, you can upload the archive file via the File Manager.  Once the file is uploaded, just select it in the File Manager to unpack it.  After the archive file has been unpacked, move it to your hosting account's "/private/" folder.
3. In the Plesk control panel, go to the Databases manager and create a new database.  Copy down the database name, the database user name, and the password, as you will need them later.
4. While still in the Databases manager, on its main page select the phpMyAdmin link for the database you just created.  This will open phpMyAdmin for this database in a new browser window or tab.  On the Import tab of phpMyAdmin, import the SQL dump of your existing site's database.
5. Either via SSH or the Plesk control panel's File Manager, modify your Drupal site's sites/default/settings.php file and update the database information in it to match what you copied down in step three above.
6. Navigate to your Web Hosting account's main URL, and you should hopefully see the front page of your Drupal site.  Try logging into it and check the Drupal status page and error logs to see if there are any problems with the site.

Updating DNS When Moving a Live Site

If your site is already live in another location, then you will need to update DNS to point your site's hostname to your new OIT Web Hosting account.  You will need to know your hosting account's server name - to get this, just look in your browser's address bar while logged into your Web Hosting account's Plesk control panel.  The server will be web-plesk##.oit.gatech.edu, where # is a number.  Either update your existing site's hostname to point to this Plesk server, or if you don't have that kind of access, ask your local IT support staff to make the change for you.  If you don't have anyone in your unit who can update DNS, you can always open a support request with OIT.

A Word on Migrating a Development Site to Live Production

If you are developing your site somewhere else and then moving it to an OIT Web Hosting account (or any other server where the DNS hostname for the site will be different from what it was in development), then you need to take special care to make sure that your internal links do not break.

When setting the URL paths for page links, inline images, attachment files, etc., make sure to enter those URLs as relative paths.  A regular (called 'absolute') URL looks like this:

  http://your-site-host-name/path/to/my/file.xyz

The relative version of that path looks like this:

  /path/to/my/file.xyz

Relative paths will continue to work even after you change the hostname of the website.  Absolute paths will cause the user's web browser to try to follow the link back to the development site.  This can cause all kinds of problems, ranging from links not working and images not showing as soon as the new site goes live, to problems that aren't detected until someone shuts down the development site months after the production site went live.

The command line savvy developer may want to search through his/her SQL database dump for the hostname of the development server before uploading that dump file to the new OIT Web Hosting account.  This is a great way of catching any absolute URL links that are still lingering about somewhere in the site.

Importing a Migrated Site into Installatron

Installatron is a service available in OIT Web Hosting that (among other things) can keep the core of your Drupal site automatically updated with security patches. To import a migrated Drupal site into Installatron, please refer to the Installatron documentation provided by OIT's Web Hosting team and watch the video tutorial on this page.

Please note that by default, Installatron does not enable automatic updating of Drupal core when importing a Drupal website into Installatron. To turn on automatic update:

1. From the front page of the Plesk control panel, look for the Installatron Applications Installer link on the right-hand side of the page.
2. In the section that gives details about your Drupal installation, select the blue wrench icon button.
3. Under Automatic Update, select 'Create a backup and update to new minor versions and security releases. (Recommended)'.
4. Select Save All. 

Play Video

Before you take a Georgia Tech Drupal site live, it is a good idea to go through the following checklist of best practices to make sure your site is secure and streamlined for production use. This checklist is designed for Drupal 7 sites on OIT's Web Hosting, but will generally apply to other environments and later versions of Drupal as well.

Within the Drupal Application

Helpful Tip: The admin interface can be accessed via the black admin toolbar at the top of any page when logged in with administrator rights.

Make Sure Core, Module, and Theme Updates Get Applied When Needed

Enable the Update manager using the following settings so that you and your team will be notified of important available updates.  Then, make sure those updates get applied in a timely fashion (but be sure to back up your site before doing so: more information on backup is below, in case anything goes wrong).

If you are using Drupal 8 or higher (considered modern Drupal), the site now needs the Composer CLI tool to manage installation and updates for Drupal core and any modules, due to more complex project dependencies.

Recommended "Available updates" Settings

Located at: Reports -> Available Updates -> Settings (admin/reports/updates/settings)

• Check for updates: Weekly
• Check for updates of disabled modules and themes: Yes (unless on a multi-site, where only 1 site should check this)
• E-mail addresses to notify when updates are available: At least TWO (2) email addresses (preferably some office-wide emails).
• E-mail notification threshold: Only security updates

Limit Access to Your Site

Avoid giving out any more access than necessary

• Make sure you have a suitable user account role for content managers that does not let them install modules, change themes, adjust low-level Drupal settings, etc.
• Ideally, only trained IT and/or web development staff should have administrator or super administrator privileges

Review your User Account List Regularly

Remove (or block) accounts of users no longer working in your unit; blocking is often the better option, as that maintains tracking of what those users did. Removing the account will require all content changes to be attributed to the "anonymous" user.

Review your Role Permissions Regularly

Roles are what map Drupal access permissions to individual users.  Review the list (found at People -> Permissions) to make sure roles do not have unnecessary permissions that put your site at risk.

Recommended "Account settings" Settings

Located at: Configuration -> People -> Account settings (admin/config/people/accounts)

• Anonymous users - Name: Visitor
• Administrator role: Super Administrator (for Drupal Express sites only; for all other sites: Administrator)
• Who can register accounts?: Administrators only
• Require e-mail verification when a visitor creates an account: Yes.
• When cancelling a user account: Disable the account and keep its content.
• Personalization
  • Enable signatures: No
  • Enable user pictures: No

Enable GT Account Authentication

• Most Georgia Tech Sites should use GT Account Authentication, which is provided by the CAS (cas) module
• Drupal Express has the CAS module already installed
• For all other sites, see the Installing CAS section for installation and configuration instructions

Recommended "Text formats" Settings

Located at: Configuration -> Content authoring -> Text formats (admin/config/content/formats)

• Order matters: place "basic text editor" at the top/first, then "minimal HTML", etc.
• "Plain text" is the only format to which Anonymous users should have access.
• If "PHP code" is present, DO NOT allow anyone to use it!

Configure Error Logging Securely

Drupal and PHP error messages shown to regular users could reveal sensitive details about your site, and just look unprofessional as well.  Use the following settings to hide error and warning messages from site visitors and keep them from overflowing your site's database.

Note: Do not enable the core syslog module if you are using OIT Web Hosting. According to the syslog module documentation, it is not appropriate for shared hosting. You should be able to find most useful debugging information by going to the Logs section in the OIT Web Hosting Control Panel and looking at the error logs.

Recommended "Logging and errors" Settings

Located at: Configuration -> Development -> Logging and errors (admin/config/development/logging)

• Error messages to display: None. 
• Database log messages to keep: 100

Enable Caching to Improve Site Performance

Recommended "Performance " Settings

Located at: Configuration -> Development -> Performance (admin/config/development/performance)

• Caching
  • Cache pages for anonymous users: Yes.
  • Cache blocks: (Depends on how often your blocks change)
  • Minimum cache lifetime: (Depends on how much dynamic content you have)
  • Expiration of cached pages: (Only matters if you are using an external cache like Varnish)
• Bandwidth optimization
  • Aggregate and compress CSS files: Yes
  • Aggregate JavaScript files: Yes

Protect Web Forms and Collected Data

Note: You should try using non-Drupal solutions for forms, such as Qualtrics, whenever possible. Keeping forms and general data out of Drupal is more secure and makes it easier to manage and later upgrade your Drupal site.

In general, do not use Drupal to store sensitive data of any kind: FERPA protected, HIPAA protected, DoD protected, or personal identity information (SSNs, birthdates, etc.)!  The exception to this rule is if your Drupal site is for internal use only and is firewalled properly to prevent access from off-campus.  Even then, you should apply all possible security protections to prevent internal hacking of your sensitive data.

If you still need to have a form on a Drupal site, use the latest version of WebForm, and install some type of anti-spam / anti-bot protection, as forms get hit by bots quickly and regularly once they are made public.

• Look at modules like Honeypot, Spamicide and BOTCHA to fend off bots
• Avoid CAPTCHA (especially the early versions) if at all possible, as it will greatly irritate your users; the latest version is more acceptable, as it does not "quiz" the site visitor as strongly as the earlier versions
• If you're resorting to CAPTCHA, consider whether or not the form can instead be locked down to just the Georgia Tech Campus only

Recommended "Site information" Settings

Located at: Configuration ->  System -> Site information

"E-mail address" is the address from which emails are sent by the site, so it should be generic, rather than the address of a real person.  Note: this must be an @gatech.edu email address for the campus email servers to accept messages from your website!

Note that the Georgia Tech web theme does not display the "Site name" set here, but rather has it's own site title fields on the theme configuration page.  However, "Site name" is used for the name shown in a web browser tab and any page bookmarks in a browser, so it needs to be set to something meaningful, and ideally identical to what you set on the theme configuration page.

Module and Library Safety Tips

• Where possible, sign up for alerts about updates to libraries being used (such as CKEditor, phpCAS, Flexslider, etc), especially security vulnerability alerts.  Drupal does not give any notifications about out-of-date libraries!
• Always turn off the following (unless you really need them):
  • PHP filter
  • Tracker
  • Comments
• Review your modules regularly and disable any that are not being used
  • Disabled modules should be uninstalled and then removed from the Drupal filesystem (move them to the /private folder if you are on OIT Web Hosting)
  • If Drupal reports that a module has been removed from its repository on the Drupal.org website, there's usually a good reason.  Remove any such modules from your site ASAP!
• Avoid keeping development-only modules on live sites. If you really need any, keep them turned off when not in use.
• Avoid alpha/beta release modules and anything that is poorly supported or not supported at all.
  • When evaluating new modules, look at the last date of a release (be wary if more than a year ago), number of sites reporting usage of the module, reputation of the module's maintainer(s), and the number of open issues in the development queue.

Check Your Site's Health

• Check the Status report (found at Reports -> Status report) and correct any problems listed
• Use the Security Review module to scan your installation for common security problems

Custom Code and the Drupal Filesystem

General Rules of Thumb

• Always write secure code!
• Never hack the core Drupal code or any third party modules!
  • Hacks will likely get overwritten when updates are applied later on.
  • Instead, look for ways to extend or adjust the code through a custom module.
• Avoid using unsupported modules, libraries or themes.
• Test anything new or uncertain in a separate instance of Drupal.  Never develop on your live site!
• Don't bother trying to hide the fact that you're running Drupal - it's really not worth the time and effort.

Drupal Filesystem Maintenance

• Avoid putting anything but Drupal related code in or under the main Drupal directory
  • Adding other files or applications complicates the upgrade process, which can result in those other files or applications disappearing unexpectedly.
    • Drupal version 8 and beyond does not support running any other applications from within or under the main Drupal directory.
  • If you manually install modules or themes, don't leave their archive files within the Drupal directory tree.  Move them to the /private directory if you want to keep them around.

OIT Plesk Web Hosting Control Panel

General Hosting Account Configuration

Owner/Administrator

• Avoid giving out hosting account access unless it is absolutely needed; only those who need to perform Drupal code upgrades should have hosting account access - content managers should never be given access to the hosting account.
• Regularly check that the administrators of a site are correct (and remove any former maintainers).

Notification Email Address for Website

Only one email address is allowed, so set to the address of a mailing list or alias that forwards to all of your site administrators.

Installatron Applications Installer

• If you are using Drupal 8 or higher (considered modern Drupal), the site now needs the Composer CLI tool to manage installation and updates for Drupal core and any modules, due to more complex project dependencies.

• The Installatron tool on Plesk does not support Composer-managed updates, and is not recommended for managing a modern Drupal site. Installatron will update Drupal core without checking dependencies, and there is a high risk of updates eventually breaking any site that includes additional modules, as most Drupal sites do.

  Plesk now offers the PHP Composer UI tool to provide limited Composer support via a site's control panel. However, updates have to be manually prompted, and the tool is limited use.

• How do I get started with Drupal on Plesk?
• Is Drupal the right choice of CMS for my site?

PHP Composer UI Tool

• While it's strongly recommended to use Composer CLI to develop and manage your site projects locally, the PHP Composer tool on Plesk provides some helpful options for managing Composer applications from your site control panel.
• How do I use the Plesk PHP Composer extension? 

SSL Configuration

Follow the guide to SSL configuration to run your site with SSL encryption (via an https:// URL).

Plesk Backup / Restoration Manager

• Before any major update or smaller update, it is recommended that you create a full backup of your site following the instructions before performing any changes/upgrade on your site.
• In case that you need to restore the site back from unsuccessful change/upgrade:
  Please note that Drupal upgrade process tends to add new files to the system.  
  
  Restoring from backup will not delete files that were added after the backup was created. Therefore, it is suggested to do a "clean" restore to avoid new files created during the unsuccessful upgrade interfering the configuration of your site before the backup.  
  
  How to do a "clean" restore with Plesk Backup Manager (under About Restoration Behavior section)

Scheduled Tasks (cron)

• Follow the guide to setting up cron so that your Drupal site will refresh content and check for security updates.

Directory structure (multi-site vs. solo site, single system per virtual host, etc.)

• This will vary depending on your site setup, but we no longer recommend using "contrib" and "custom" subfolders in the sites/all/modules folder.

URL Redirects

• These are usually created in your .htaccess file (always keep a copy of the latest in your /private directory).
• Check that your redirects did not get overwritten when your site's Core code was late updated.

Additional ideas can be found in the following:

• Securing Your Drupal Site (Last updated in 2016)
• List of security-related contrib modules (Last updated in 2016)
• Supporting Drupal Over the Long Run (BadCamp 2012)
• Performance for Site Builders (2012)

Updates patch Drupal to add new features and protect against discovered vulnerabilities, keeping your sites working optimally. Always test new updates on a development site before applying them to your live, production site.

Drupal 9 has a different method of doing updates.  Please see the soon-to-be-added pages for Drupal 9 update instructions.

Drupal Updates Sub-Topics

Most Drupal 10 installations on campus will be hosted on OIT Web Hosting and managed through composer (not Installatron as was used for Drupal 7 and earlier).  Updating Drupal 10 under composer is relatively straightforward, but does involve several steps:

1. For good measure, open the site in a web browser window, log in, and put the site in maintenance mode.  Leave this window open so that you can return to it as needed.
2. In a separate browser tab/window, log into the site's Plesk Control Panel through OIT Web Hosting.
3. While all OIT Hosting Accounts now have automatic updates enabled, it doesn't hurt to run a full manual backup to capture the most recent changes, just in case something goes wrong while updating.
   1. Go to the Backup & Restore button in the right-hand sidebar on your site's Plesk control panel
   2. Select the Backup button and follow the prompts
4. With your backup complete, go to the PHP Composer tool in your site's Plesk Control Panel
   1. Under Package Dependencies you should see an Update button.  Select this button.
   2. You should get a pop-up modal showing the update progress.  This may take a little while, so please be patient.
5. When the updates are finished, return to your first browser window (the one that is logged into your Drupal site) and select the Drupal icon in the administrative toolbar for your site, then select Run updates to run database schema updates.
   1. If you have any trouble here, you can try going to the URL path of your site's home page with "/updates.php" added to the end of the URL.
6. When the database schema updates are complete, test your site and make sure it still functions as expected.
7. Disable maintenance mode to make the site open to the public again.

The following information is currently targeted to those site admins who have a site built on a custom theme implementation or have written custom modules for Drupal 9.

If you are using the standard Drupal 9 Drupal Express provided by Institute Communications, you should wait until they release a new version of the Georgia Tech theme package before trying to upgrade to Drupal 10.

A list of things to be watchful for when upgrading to Drupal 10 (to be expanded in the near future):

• There's a new 2.x version CAS module and 2.x version External Auth module that must be installed before upgrading.

• For that matter, use the Available Updates report to scrutinize all of your modules, even the ones that show up in green.  A module with a major version update can still render in green if you have the last release of the previous major version.

• If you are running a Composer manged site, install the Upgrade Status module to check your site for upgrade issues that need to be corrected.

• If you have your own custom modules, you'll need to go through all of them and check for Drupal 10 compatibility issues:

  • drupal_get_path() and drupal_get_filename() are removed from Drupal 10

  • \Drupal::entityQuery now requires an accessCheck() parameter to work

  • The themes Seven, Classy and Stable have been removed from Drupal 10 and need to be disabled before upgrading, unless you plan to use the contrib versions, in which case you must install those versions before upgrading.

    • The administration theme of choice is now 'Claro' - you should switch to Claro and uninstall Seven before trying to do an upgrade to Drupal 10.

    • NOTE: If a theme you are using has enabled Classy or Stable, you must use a hack to disable them, as they are hidden in the admin GUI by default.  See Drupal Issue #3328016 for more details.

      • Short summary: If a theme uses another theme as a base theme, the other theme gets enabled at install time.  However, Classy and Stable are hidden themes, so they don't show up in the admin GUI, thus you can't uninstall them through the GUI.  Unfortunately, Drupal 10's update.php script expects them to be uninstalled.  The hack involves modifying both theme's .info.yaml files to unhide them, allowing you to uninstall them.  Take note that even after unhiding a theme, you still won't be able to uninstall it if an active theme refers to it as a base theme.  Deal with those active themes first (uninstall them or update them to not rely on Classy or Stable), then flush caches and you should be able to uninstall Classy and Stable after unhiding them.

    • If you are using a theme based on Classy, you have two choices: install the contrib version of Classy, or merge everything from Classy into your theme.  Do note that Classy uses Stable as a base, and Stable has also been removed from Drupal 10, replaced with Stable9.  Stable9 does exist in Drupal 9.5.0, so you can port your theme over while still running under Drupal 9.  However, you'll have to use the hack in the previous bullet point to enable Stable9 before you can get another theme to use it as a base theme.  This is because Stable9 is also hidden, like Stable and Classy

  • Last but certainly not least, update the core_version_requirement setting in each custom theme and module's .info.yml file to include ^10

• Deprecated Modules: The following need to be fully uninstalled before upgrading, unless you are choosing to use the new contrib versions, in which case you need to install the corresponding contrib version before upgrading:

  • CKEditor 4 (if you're removing it, don't forget to remove all CKEditor 4 add-on modules as well)
  • Color
  • Quickedit
  • RDF
  • Aggregator
  • Hal

Migration, not upgrade

Drupal 8, released in November of 2015, was a major rewrite of the underlying Drupal code (Drupal's core engine and APIs). Because of the multitude of changes, there is no direct in-place upgrade path to go from any earlier version of Drupal to Drupal 8 or later. Instead, Drupal 7 and earlier sites must be migrated to Drupal 8 or later, which involves setting up a whole new Drupal 8 website and copying into it (manually or automatically) the content of the older website.

All Drupal 7 sites that are to remain on Drupal should be migrated to Drupal 10, the latest version of Drupal.

Requirements and Web Hosting Support

Drupal 10 requires a hosting environment running at least PHP 7.4 or later, which is available on OIT Web Hosting. OIT does not currently support the use of Drush or command line access to Composer. However, the Plesk control panel GUI allows for composer set up and management.

The easiest way to get started with the Georgia Tech branded version of Drupal 10 is to request an installation from OIT. You can select this option when requesting a new OIT Web Hosting account, which is usually the best way to go.  In short, you would set up a new site in a new hosting account using a temporary domain name, and then once you have copied over all of your existing content, you would shut down your old site and repoint your real domain name to the new hosting account. 

Note

If this sounds a little too technical for you, you should consult with your local IT support staff, who should be able to help you through anything concerning domain names and repointing them.

Georgia Tech Migration Roadmap

Beyond PHP support, each Georgia Tech unit website will need several extra components to be fully usable. The following table is an attempt to start tracking the status of the components needed for Georgia Tech Drupal 9 sites, and it will be updated as releases and additional information come available.

Complete Migration Process

Kevin Pittman has posted a guide to migrating from Drupal 7 to Drupal 10 that includes a lot of planning tips and technical details.

Notes, tips, and tricks for upgrading a Drupal 8 site to Drupal 9

Moving to Drupal 9 from Drupal 8 does not involve near as much planning and preparation work as previous major version upgrades thanks to changes the Drupal organization has made to the development process.  Instead of Drupal 9 introducing a new batch of features, new features have been added gradually over the major point releases of Drupal 8.  The key changes with the first release of Drupal 9 will be to remove deprecated (old and no longer used) code, and to upgrade the underlying Symfony framework.  On the surface, though, you should not see any notable differences between Drupal 8.9 and Drupal 9.0, assuming you have prepared your site properly.

Preparation

Basic Requirements

• Drupal 9 requires PHP 7.3 or higher (7.4 is preferred). If you are on OIT Web Hosting, you should be able to set your PHP version now via your site's Plesk Control Panel.

• Drupal 9 requires a settings.php change:
  • The line beginning with "$config_directories['sync'] =" has to be changed to "$settings['config_sync_directory'] ="

  • Note: You can do this before upgrading, as Drupal 8.9 will work with either version of the setting.

• To upgrade to Drupal 9, you must be on Drupal 8.9.0 or higher.
  • If you are already on 8.9, make sure you have the latest patch release to get the smoothest transition

  • If you are on anything earlier, upgrade to the latest patch release of 8.9 first, then upgrade to the latest 9.0 release.

• Drupal 9 requires all active themes and modules to declare Drupal 9 compatibility:
  • Compatibility is indicated by a line in the theme or module's .info.yml file that starts with "core_version_requirement:"
  • Check and update all custom and contrib modules.
• Drupal 9 (as did Drupal 8.9) uses CKEditor 4.14.0, but Drupal 9 seems to be stricter about CKEditor plugins. If you are using any add-on CKEditor plugins, check each one to see if there's a 4.14 specific version and upgrade as needed. Composer should maintain the compatible plugin version with a Drupal 9-compatible release.
  
  As an example, Balloon Panel, used by Accessibility Checker, was one that needs to be up-to-date to work in Drupal 9.

Checking Module / Theme Compatibility

There are several tools available that are supposed to check your site's modules and themes for Drupal 9 compatibility. The present options either require the ability to run PHP at the command line or require your site to be managed through Composer (such as Drupal Express websites).

Upgrade Status Module

The Upgrade Status module can perform a website audit to determine which modules, themes, and add-ons are Drupal 9 compatible.

Command Line

If you are comfortable with running simple commands at the Linux command line, you can get a quick overview of your modules declared compatibility by going to the main modules directory and running the following command:

  grep "core" */*info*

For any module where you do not see a line with "^9" near the end, you'll need to do some testing and research to see if the module will work with Drupal 9.  Check first for a new major version release, and if there is none, you could try the instructions given below for testing a previously Untested Release to see if it causes any problems.

Process

Once you've completed all of the preparatory steps, upgrading is the same as if you were upgrading to another point release of Drupal 8. 

As with any major update, make a full backup (filesystem and database) before you begin, just to be safe.

Afterward, test major website capabilities thoroughly, since a lot of old code has been removed and the underlying Symfony engine has received a major upgrade.

Institute Communications update process

Refer to Institute Communications' gt_installer Drupal 8 to Drupal 9 update process to update GT Theme, GT Tools, and GT Profile to their latest versions.

Issues

Semantic Numbering - New Major Releases

As more time goes by, more module developers will move to the new semantic numbering system that is not tied to a Drupal version number (e.g. 7.x-1.0). Typically, if a module was at say version "8.x-3.5" then the next major release done under the new numbering system would be "4.0.0". You'll have to check carefully for this change, as Drupal alerts major version releases (8.x-3.5 to 4.0, for example) as "Other versions available".

However, in the case of modules like Webform, you may find you are expected to upgrade to the next major version when you upgrade your site to Drupal 9. Module version updates to the next major version can be done easily if you manage your site with Composer. Otherwise, you'll have to do this by hand at the filesystem level (Drupal won't upgrade to a new major version via the GUI).

As with most major version upgrades, manually run schema updates (go to update.php after updating).

Known Problem Modules

• Devel has a new 4.0.0 release just for Drupal 9, but the popular Kint debugger sub-module is gone from 4.0.x. To get that functionality you have to use composer to install a Kint plugin for Devel 4.0.x or use the devel_kint_extras module. That's a big complication if your site is not set up to be managed by composer. As a workaround, you can download the PHAR version of Kint and manually include it in your site to get its functionality. Please note that the manual library process is not as streamlined an install as a prepackaged module.

• Webform 8.x-5 is not compatible with Drupal 9 at all and will actually break the update.php process. If you use Webform, do not attempt to upgrade to Drupal 9 until you have upgraded Webform to its new 6.0 release.

Installing the Georgia Tech Theme

You will need to download both the current Georgia Tech Drupal Theme package, and the GT Tools module.

1. Install the GT Tools module into your sites/all/modules directory, and the Georgia Tech Drupal Theme package into your sites/all/themes directory.
2. Log into your site with administrative privileges and enable the GT Tools module.  Please note that you do not have to enable the GT Content Types or GT Directory sub modules that come with GT Tools.
3. Go to the Appearance administration page and enable the "Georgia Tech - Drupal 7 Theme" and make it the default theme.
4. After enabling the new theme, follow the Settings link shown below its name to configure the theme's settings, using our GT Theme Settings Guide as a reference as needed.

Extending the Georgia Tech Theme

The recommended way of extending the Georgia Tech Theme to meet your unit's special needs is to create a sub-theme instead of modifying any of the files in the Georgia Tech Theme.  This way, when new versions of the official theme are released, you can just drop them into place and not have to figure out all the different things that you customized.

As a way to get started quickly, there is an unofficial GT Sub-theme package that you can use as a base for your own custom sub-theme.

An important hint for those new to sub-themes:  on your Appearance administration page, you set your sub-theme to be your enabled and default theme.  It will then include everything that it needs from your base theme (the official Georgia Tech Drupal Theme).  For this reason, you must leave the Georgia Tech Drupal Theme installed on your site, and it's a good idea to leave it enabled as well.

For advanced developers, there is also a Sass based version of the official Georgia Tech Drupal Theme.

Upgrading the Georgia Tech Theme

It is highly recommended that you first test any new version of the official Georgia Tech Drupal Theme against a copy of your website to make sure you fully understand the effect it will have on your pages and content.

If you have done all of your customizations in a sub-theme, then upgrading the official Georgia Tech Drupal Theme is very easy:

1. Download the latest version of the Georgia Tech Drupal Theme
2. Backup the existing files in your sites/all/themes/gt directory and then remove the directory.
3. Remove the sites/all/themes/gt directory.
4. Install the Georgia Tech Drupal Theme package into your sites/all/themes directory.
5. Log into your site with administrative privileges and flush all of the caches.  This can be done on the Configuration -> Development -> Performance administration page, or via the 'Home' menu if you have the Admin Menu third-party module installed.
6. Go to the Georgia Tech Drupal Theme settings page and verify that all of the available settings are correct.  Note: it has been observed that sometimes after upgrading the theme, you will find all of the settings fields blank the first time you visit the settings page.  If this happens, simply switch to the global theme settings page and the go back to the GT theme settings page, and your old settings should be restored.

Please note that a new version of the Georgia Tech Drupal Theme could cause conflicts with custom CSS and template code in a sub-theme, so you'll have to watch for these issues and update any custom CSS/template files accordingly.

The GT theme version 2.x offers a variety of settings options.

How to Manage Theme Settings

To manage these options:

• Go to: yoursite.gatech.edu/admin/appearance/settings/gt_subtheme
• Use the Appearance link if using the Administration Menu module

Description of Theme Settings

These include:

Georgia Tech Logo Options

Select the default GT logo, or go with one of the college logos. You can also upload a file to use, but it must be a transparent .png, and be within the specified dimensions -- plus be an official logo approved by Institute Communications! Contact Institute Communications if you need assistance getting a logo generated in the proper format.

Styling Version

This setting (only available in versions 2.5 through 2.7) configures which CSS/styling is applied to the GT website.  It allows you to switch to the new layout/style treatment (2.5) or stay backwards-compatible with previous styling. This is to help avoid "breaking" any styling folks may have done via a custom subtheme. The version 2.5 styling option also includes support for a couple of block classes that are added through the GT Tools module (/admin/config/system/gt):

New CSS styles for adding icons to block titles:

• icon-institution (displays: http://fontawesome.io/icon/university/)
• icon-mortar-board (http://fontawesome.io/icon/graduation-cap/)

New CSS styles for adding colored backgrounds to block titles:

• block-title-bg-gt-blue - GT Navy blue background w/ white text
• block-title-bg-gt-gold - GT "Buzz" gold background w/ white text
• block-title-bg-gray - "Dark" gray background (#646464) w/ white text

Site Header

These settings configure site header actions.

1. Site Header Title: Same as the previous theme. The text provided here will appear in the site header, to the right of the main logo. The text will be set in "Buzz" Gold.
2. Hide Home Page Title: Check this box if you want the default page title text to NOT appear on your home page. Note that this is NOT the Site Header Title (as mentioned above,) but the node title of your home page for your site.
3. Search Options: (Removed in version 2.7) Select to have your search be the built-in Drupal search, the campus Google appliance, or user choice.
4. Breadcrumb Options: By default the breadcrumb will list a link back to the main Georgia Tech site homepage first. If you'd like to have another default link always appear after the Georgia Tech link use these fields.

​Super Footer

These settings relate to the superfooter at the bottom of each page.

1. Remove Superfooter: (Added in version 2.7): completely hide the superfooter
2. Super Footer Menus Setup: The Full Georgia Tech Default option will give you the exact same set of super footer menus that appear on the home page of www.gatech.edu. The Georgia Tech Minimum option will give you just the menu from the left column in the super footer of the home page at www.gatech.edu, but the menu will be broken up into two shorter menus. The Configurable option allows you to have three fully configurable menus in your site's super footer.
3. Collapsed Super Footer: Check this option if you would like to have the super footer collapsed by default. If this option is checked a "Resources" tab will appear above the lower footer, which serves as an open/close trigger for the super footer.
4. Campus Map Image and Custom Street Address: By default the site super footer area will show an image of the campus map plus link to the map site, and the official GT mailing address. You can opt to upload your own map image, and have it link to where ever you'd like, plus enter your address.

Footer Login

These settings configure site footer login actions.

1. Show a login link in the footer.
2. Redirect to current page: (Added in version 2.7) instead of being redirected to homepage after you log in.
3. Alternate Login URL: (Added in version 2.7): If you use a different URL to log in to your site, provide that full URL (i.e., http://editor.mysite.gatech.edu).

The GT Tools module is required when using the GT Theme and should be installed before the theme on your Drupal 7 site.  It provides some additional functionality that Drupal doesn't support directly in a theme package, so this functionality had to be provided in a separate module.

GT Tools includes a sub-module called GT Content Types, which provides three new page layouts via custom content types: "Horizontal Landing Page", "Vertical Landing Page", and "Multipurpose Page".  If you want to use this sub-module, you must install the 2.2 version (or newer) of the blockreference module (older versions 2.0 and 2.1 don't work).

Please see the introduction to contrib (third-party) modules before installing anything listed on this page.

The following information is provided as-is with no warranty or guarantees of any kind!  While members of the campus community have recommended the following modules for their listed purposes, it's perfectly possible you could blow up your Drupal website if you don't know what you're doing and install them incorrectly or alongside other modules that are incompatible.

Most descriptions are borrowed from the module's home page on the Drupal.org website.

The Drupal community on campus has found a number of modules which help with using CKEditor:

IMCE

Versions: Drupal 10, 7

​IMCE can be used for managing images, and you might even use imce for files, as well.

Installation instructions for IMCE:

1. Download, install, and configure IMCE.
2. Remove the default Image button.
3. Add the IMCE button.
4. Enable the option "Plugin for inserting files from imce without image dialog".
5. Enable the option "Plugin for inserting Drupal embeded media".

LinkIt

Versions: Drupal 10, 7

LinkIt can be used for managing URL links to pages on the site and outside of the site.

Installation instructions for LinkIt:

1. Download, install, and configure LinkIt
2. Remove the default URL button.
3. Add the LinkIt button.
4. Check "Support for Linkit module".

Image Resize Filter

Versions: Drupal 10, 7

From the Drupal.org site:  Image Resize Filter makes it easy to resize images, especially when combined with a WYSIWYG editor such as tinyMCE, CKeditor etc. Users never have to worry about scaling image sizes again, just insert an image and set it's height and width properties in HTML (this is done automatically by WYSIWYG editors) and the image is resized on output to match the HTML.

Embedding Georgia Tech MediaSpace Repository Content

A good solution for the Georgia Tech MediaSpace (Kaltura) repository has not been developed yet.  In the meantime, an experimental MediaSpace embed module is available for Drupal 7 and Drupal 10 from the developer who created the embed module for the now retired OIT Digital Media Repository.  Use at your own risk!

• IAC Support for oEmbed Formats for Drupal 10 (oEmbed support for MediaSpace, YouTube, Vimeo, and Google Maps)
• GT Kaltura Module for Drupal 7

After installing either module, you will have to add the new input filter to your preferred text formats.  Make sure to set the ordering so that the filter comes last after all other filters.  This ensures that the filter's Javascript code does not get filtered out by any of your other text filters.

There is also a method now for enabling MediaSpace as an oEmbed provider in the Drupal Media library system.  The Media Library works outside of CKEditor and would be used in conjunction with custom blocks that contain Media fields (typically used with Layout Builder based page.)

Embedding YouTube and Vimeo Videos

Option #1 - Video Embed Field (Drupal 7 or 10)

1. Download, install, and enable the Video Embed Field module.
2. Add the new video field type to one or more of your Drupal Content Types.
3. Content editors can now add videos to nodes of those content types by inserting the right linking details into the video field.
4. WebWash provides a tutorial about video styles you can create with the Video Embed Field module.

Option #2 - Video Filter (Drupal 7)

1. Download, install, and enable the Video Filter module.
2. In the administrative configuration area of Drupal under Content authoring -> Text formats, configure each text format that you want to be able to use embedded videos.
   1. Enable the video filter.
   2. In the Filter processing order section, move the video filter down to the bottom of the list so that it is applied after all other filters.
   3. Don't forget to save your changes.
3. On pages that use one of these configured text formats, you can now insert a video shortcode to create an embed of a supported video type.  See the download page at the link above for the full list of supported video services and formats.
4. Example shortcode for embedding a video:

[ VIDEO::http://www.youtube.com/watch?v=98nNpzE6gIs::aVideoStyle ]

Option #3 - Ivan Allen College oEmbed Support Module (Drupal 10)

1. Install the IAC Support for oEmbed Formats for Drupal 10 module
2. Add the new "Embed remote content with oEmbed links" input filter to your preferred text formats
3. Where you want to place a YouTube video, just paste in the video's oEmbed URL (see the oEmbed module's instructions for full details)

Option #4 - Drupal Media Library and oEmbed

You can use the standard instructions for adding an oEmbed provider to Drupal's Media Library to enable the use of YouTube, Vimeo, and some other video services.  In most cases YouTube will be enabled out-of-the-box.  The Media Library works outside of CKEditor and would be used in conjunction with custom blocks that contain Media fields (typically used with Layout Builder based page.)

The Easy Way for IFRAME and JavaScript Embeds

The "Full HTML" format in an out-of-the-box installation of Drupal 10, or in Drupal 7 with CKEditor installed without the WYSIWYG plugin should already allow for IFRAME embeds and JavaScript embeds.  If you haven't added any tools to restrict this, then you're all set.

For more restrictive CKEditor configurations, such as the GT Editor version of CKEditor for Drupal 7, you'll need to add a new text format (Configuration -> Content authoring -> Text formats and editors) that at a minimum allows IFRAME embeds.  If the service you want to embed from also requires you to include a snippet of JavaScript, then you'll need to enable that for your new text format as well.  You'll then want to restrict this format to site administrators (which should hopefully be a separate role from that of your site's day-to-date content creators and editors).  You can then add blocks where needed and use this new text format so that you can add your embed code to the block.

The Preferred Way for PHP Code

By far, the recommended way of adding custom PHP Code to a page of a Drupal site is by creating a custom module, which is a type of plugin that adds extra functionality to your Drupal site.  This does require a reasonable amount of PHP coding experience and time to get familiar with how to code for Drupal.  The Drupal organization has made some tutorials available to help get you started:

• Drupal 10 custom module tutorial
• Drupal 7 custom module tutorial

For a lot of cases, the right approach is to create a module that implements its own dynamic block(s).  These will act like a custom block that you create in the Block Layout interface, only the content will be generated by your module instead of being entered through the Drupal user interface.  Thus, you could implement a block that has your external embed code or custom PHP code output as its content, then place that block on whichever page you want the output to show.

The Absolutely Wrong Way for PHP Code

Do not try to use the PHP Code Filter module under any circumstances! This module used to let you put PHP Code directly into CKEditor and have it get processed when the page is displayed. It is very unsafe and can't even be turned on in Drupal 7 unless you upgraded to Drupal 7 from an earlier version that had it turned on. In addition, the module has been completely removed from Drupal 8. If you are already using this method for custom PHP, you should look into switching to one of the following methods as soon as possible.

The Georgia Tech GT Editor module for Drupal 7 is built around CKEditor, but provides a great deal more control over what content editors can create, preventing them from doing things that might be dangerous (embedding JavaScript, for example.)

This is a community supported project, meaning it is not officially supported by OIT or Institute Communications.

GT Editor Guides and Tutorials

If not properly secured, forms can easily be used by hackers and automated "bot" programs to gain access to information within our sites, deface a site, or or even gain access to all the sites on a shared server.  The following is a non-exhaustive list of tips for making any web-based form more secure.

Form Safety Tips

• Never ask for sensitive information or information you don't need. Examples include birth date, credit card number, student data (including GTID), and other sensitive data.
• Protect your form with CAS login (for campus) or with CAPTCHA (for people without GT accounts).
• Remove old data and forms.
• Regularly archive and then delete old submissions and forms
  • Go in every month or semester and download the old submissions to a spreadsheet, and then delete those submissions from the website.
  • Close or remove web forms when they are no longer in use.
• Use SSL / HTTPS for your site.

Twig stubs and code-samples to aid your Twig template development.

External Resources

• Twig data stubs (from the Ivan Allen College's web development resources website)

Per Georgia Tech's accessibility requirements, certain fields likely need additional explanatory text accompanying them:

Video Fields (e.g. YouTube)

Any publicly available video must be captioned for end-users. MediaSpace and YouTube automatic captions are not enough to meet full guidance: any automatic captions must be manually reviewed and corrected.

Please see the Video Captioning and Audio Transcripts page of the Resources for Webmasters website for more information.

Image Field

Any non-decorative image must have alternative text describing the visual component of the text.

Please see the Ivan Allen College's Web Accessibility Primer for additional information on alternative text for images.

You can find Georgia Tech's license for Font Awesome 5 on Github.

Recommended Usage

We strongly recommend utilizing the SVG icons for usage in your Drupal website, due to accessibility and compatibility concerns.

Here's how to whitelist HTML tags in your module output that are normally stripped out by the XSS filter:

    $tagList = array('input');
  
    return array(
      '#markup' => $buffer,
      '#allowed_tags' => array_merge(\Drupal\Component\Utility\Xss::getAdminTagList(), $tagList),
    );

And here's how to allow data URLs in your module output for displaying images with data that you've already pulled in from a data source (code updated 2017-12-11 to a better format that avoids whitescreening in certain use cases):

  $allowedProtocols = \Drupal\Component\Utility\URLHelper::getAllowedProtocols();
  $allowedProtocols[] = 'data';
  \Drupal\Component\Utility\URLHelper::setAllowedProtocols($allowedProtocols);

Useful modules

List of potentially useful Layout Builder Extensions within the Layout Builder Ecosystem:

• Layout Builder Restrictions
  Lets you restrict which block types appear in Layout Builder's Add Block panel - very useful
• Layout Builder Modal
  This module lets you add and configure existing blocks in a modal in the Layout Builder UI.
• Layout Builder Styles
  This module allow site builders to select from a list of styles to apply to layout builder blocks and layout builder sections.

• Layout Builder Kit
  An assortment of pre-built block types for use with Layout Builder

• Layout builder library
  Provides a layout library allowing content editors to pick from a list of pre-defined layouts.

Please see the Drupal 8 documentation for a complete list of contributed modules compatible with Layout Builder.

Local modules

Locally written modules:

• Layout Builder Operation Link
      Add a 'Layout' link to content entities in the Content listing view

Media Library in Drupal 10 offers a lot of great functionality for managing and reusing images (and other media types), but out-of-the-box it has a notable accessibility issue.

If you try to configure an image media type so that the user can select the thumbnail image and get the full-size version, the option for this (setting "Link image to" to "File") gives you only a link around the image, with no way to include the media item's built-in Name field.  Worse, the link will be presented to screen readers with the image's alternate text, which may not be appropriate for link text, and training content managers on how to handle this special usage of the alternate text field would be an uphill battle.

Correcting this problem requires both changing your media type configuration and adding a custom template:

Media Type Configuration

1. Edit your Media type and switch to the Manage display tab
2. Move the Thumbnail and Name fields up above the "Disabled" separator, but leave Image enabled as well.
3. Configure the Thumbnail settings as desired, then configure Image with the "URL to image" format pointing to the "original image".
4. Save your changes.

Custom Template Configuration

First, create a template file named "media--XXXXX--default.html.twig" where "XXXXX" is the machine name of your Media Type.  Place the following inside it:

{%
  set classes = [
    'media-library-item',
    'media-library-item--grid',
  ]
%}

<div{{ attributes.addClass(classes) }}>
  <a href="{{ content.field_media_image.0['#markup'] }}">
    {{ content.thumbnail }}
    <span class='visually-hidden'>Full Size Version of Image "</span> {{ content.name }} <span class='visually-hidden'>"</span>
  </a>
</div>

If you put your template into a sub-theme, then just flush your caches and it should take effect.  If you put your template into a module, then add the following to your .module file:

function YYYYY_theme($existing, $type, $theme, $path) {
  return [
    'media__XXXXX__default' => [
      'base hook' => 'media',
    ],
  ];
}

Replace "XXXXX" with the machine name of your media type, and replace "YYYYY" with the machine name of your module.  Flush your caches, and the template should take effect.

Scott Jacobson, Desmond Gardfrey, and Eric Sembrat were able to get Georgia Tech's MediaSpace working as an oembed provider for Drupal media.  Below is the method they developed.

1. Add the OEmbed Providers module

2. Add a custom provider (/admin/config/media/oembed-providers/custom-providers). The provider name must be entered as MediaSpace @ Georgia Tech with the '@' symbol in the middle.
   
   Provider Name: MediaSpace @ Georgia Tech
   Provider URL: https://mediaspace.gatech.edu
   Endpoint #1 - Endpoint schemes: https://mediaspace.gatech.edu/id/*
   Endpoint #1 - Endpoint URL: https://mediaspace.gatech.edu/oembed
   Endpoint #1 - Discovery: (Select this checkbox)
   Endpoint #1 - Available formats: JSON (Select this checkbox)

   

3. Add a provider bucket (/admin/config/media/oembed-providers/buckets)

   • Check the option Allowed Providers "MediaSpace @ Georgia Tech"

4. Add a media type of MediaSpace @ Georgia Tech (/admin/structure/media/add)

   • Select Media source MediaSpace @ Georgia Tech and select the Save button.  The field mapping is unnecessary unless you want to override something.

5. Add your oEmbed media link to a Media type (/media/add/)

6. To add Media within CKEditor:

   • Add the "insert from media library" button to one of the CKEditor toolbar text formats (/admin/config/content/formats)

     • Make sure that the embed code is wrapped in CSS like <div class="video-container"></div> when entered via CKEditor.

   • Add the following CSS via your custom theme or a custom module:

     .video-container { position: relative; overflow: hidden; width: 100%; }
     .video-container::after {​​​​​​​ display: block; content: ""; padding-top: 56.25%; }​​​​​​​
     .video-container iframe {​​​​​​​ position: absolute; top: 0; left: 0; width: 100%; height: 100%; }​​​​​​​

7. You could also make a custom block type with a TWIG file, wrapping the embed in <div class="video-container"></div> and adding the above CSS to your custom theme or a custom module.

8. To Be Determined:  How to add the MediaSpace @ Georgia Tech provider to the custom block types Call to Action and Video Embed.  (Editor's note: This should be doable by modifying the existing media types used by those blocks and adding the provider as an Allowed Provider.)

Here's a quick reference guide to working with the new configuration management system. You'll need this if you want to build a module that adds its own configuration to Drupal during its installation process:

Simple Configuration API | Drupal.org

Editor's Note: Information on Obtaining and SSL Certificate and Setting Up SSL on OIT Web Hosting with an External Domain Name has been moved to the Georgia Tech Resources for Webmasters website.

Additional details about enabling SSL for Drupal can be found in Jimmy Kriigel's posting in GitHub about SSL and Drupal sites.

Part I: SSL Certificate

See if you need an SSL Certificate, and if so, obtain your SSL Certificate. In short, if your site is a top-level site on OIT Web Hosting, you can use the existing SSL certificate available on your hosting server - no special configuration on the Plesk control panel side is needed - just follow the steps in Part II below.  If your site's hostname is a subdomain of a department domain (e.g. something.yourdepartment.gatech.edu), then you will have to see if the Plesk certificate includes your "yourdepartment.gateh.edu" domain name - if so, then you should be good to go - if not, then you'll need to obtain a certificate (see "obtain your SSL Certificate" above).

Part II: Configure Your Drupal Instance

Edit Your Site's .htaccess File

Add the following directly after "RewriteEngine On" in your site's .htaccess file:

RewriteCond %{HTTP_HOST} ^www\.(.+)$ [NC]
RewriteRule ^ https://%1%{REQUEST_URI} [L,R=301]
RewriteCond %{HTTPS} !=on
RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

What this will do is catch any requests that have "www." before your site's hostname and redirect the user to the non-"www." version of the URL.  Then, if the user is not using HTTPS, it will redirect the user to the HTTPS version of the URL to ensure that HTTPS / SSL security is always used.

Edit Your Site's settings.php File (Drupal 7 only)

Find the line for "$base_url" (or add one if this setting is not defined), and set it to the the fully qualified domain name of your site, like so:

$base_url = "https://foobar.gatech.edu/";

Important Note:  The settings.php file is usually protected from editing, so you may have to modify its access permissions before you can modify it.  Try editing it from the File Manager in your hosting account's Plesk Control Panel, as this may make it easier to override those protections.

You can restrict your site so that only people who are on-campus (or using the VPN) can access it. This is a great idea for internal-use-only sites and also for all of your development/test websites if you are not using a local stack.

Using .htaccess Configuration

Here's the code to put into the .htaccess file in the root directory of your site (on OIT Web Hosting, this goes under httpdocs or httpsdocs usually):

RewriteEngine On
RewriteCond %{REMOTE_ADDR} !^130.207.
RewriteCond %{REMOTE_ADDR} !^128.61.
RewriteCond %{REMOTE_ADDR} !^143.215.
RewriteCond %{REMOTE_ADDR} !^192.93.8.
RewriteCond %{REMOTE_ADDR} !^10.
RewriteCond expr "! -R '172.16.0.0/12'"
RewriteCond expr "! -R '100.64.0.0/10'"
RewriteCond %{REQUEST_URI} !/vpn-message.html
RewriteRule ^.* /vpn-message.html [R=303,L]

The first three lines cover the main Atlanta campus, while the fourth line (192.93.8.) covers GT Lorraine in France, and the last 3 private campus IP space.  The last RewriteCond line is needed to whitelist your message to off-campus users - otherwise they'll end up in an infinite redirect loop.  Also note the 303 redirect status on the last line: this tells the browser to check back with the server and not cache the redirect.  If you use 301 instead, then a user who connects from off-campus and gets your message file will continue to get it even if they then connect to the VPN.  Using 303 ensures that they'll actually get to your site once they've logged into the VPN.

The method above will direct all outside users to /message.html on your site, where you can post a message about the site being for on-campus use only. An alternate method (shown below) will just give users a 403 Forbidden error, which might be good enough in many cases.

Alternate Method with Basic Apache HTTPD Configuration

The following may be a little easier to maintain than the as the campus network expands and evolves than the version above, but this version will simply give the off-campus user a standard 403 Access Denied error message without any further explanation.

For Apache 2.4 .htaccess

Require all denied
## All Atlanta Campus & VPNs
Require ip 130.207.0.0/16
Require ip 128.61.0.0/16
Require ip 143.215.0.0/16
Require ip 10.0.0.0/8
Require ip 172.16.0.0/12
Require ip 100.64.0.0/10
## GT Lorraine
Require ip 192.93.8.0/24

Using a Firewall

If your website is not on OIT Web Hosting, then you can also limit access through firewalls:

Software Firewall

This kind of firewall you have to set up and maintain yourself, so you need to have some basic networking knowledge to get it configured correctly.  On the other hand, you can reconfigure it yourself whenever necessary.  On UNIX style systems (Linux, Mac OS X, etc.), you can use either  ipfilters or ipfw.  On Windows servers, Microsoft provides its own firewalling tools - check your Windows server documentation for more information.

Hardware Firewall

This kind of configuration has to be done via the GT Networking Firewall web application by someone authorized to make changes to the subnet that your server lives on.  The upside to this option is that you don't have to know anything about networking, and you don't have to worry about your firewall breaking when you run upgrades on your server's operating system.  The downside is that if you don't have access to mange the firewall for your subnet then you'll have to send your requests for changes up to whomever manages your subnet.

Central Authentication Service (CAS) based single sign-on is the main method of doing authentication via GT Account Usernames for Drupal website logins.  Once users have logged into the GT CAS system, the can access any Georgia Tech website that utilizes CAS without having to enter their GT Account Username again, as long as they don't completely close their browser or clear their browser's cookie cache.

CAS Guides and Resources

Lightweight Directory Access Protocol (LDAP) is an open protocol for sharing directory information and can be used as an alternative to CAS to allow users to log in to a web application using their GT Account Username and password.  Unless your application doesn't support CAS, it's best to use it instead of LDAP, since LDAP requires obtaining a special GTED LDAP user account for your application.

If you just want basic directory information for users without the ability to do user authentication, there is a public GT LDAP server called 'Whitepages' that can be queried from any server or workstation on-campus.

LDAP Guides and Resources

All Georgia Tech users who have been enabled for two factor authentication (2FA) are required to log into CAS with their two-factor token via the Duo 2FA service.  As of summer 2017, this includes virtually all campus employees, and will soon include all students.

So, long story short, there is no reason to add your own two-factor authentication to your Drupal websites - you would, in effect, just be creating three-factor authentication, which would likely create more headaches than benefits.

More information on the campus program can be found on the OIT Two-Factor Authentication website.

The GT Account Username is the standard computer account for everyone at Georgia Tech.  It is used to access a variety of systems including TechWorks, BuzzPort, and Mercury, and can be used to access your Drupal site by installing the CAS module.   

You may often find that need to add someone to a group in Mercury or to your Drupal site, and you need to know the person's GT Account Username.  Here are several ways that you can look up that information:

Using Office 365

[Instructions courtesy of Noel Moreno]

• Go to the "People" area (click on the "waffle" in the upper left, then select "People").  
• In the left column, check the radio button for "Directory".  
• Enter the person's name, email address, partial name, etc. in the search box.  
• Results are returned on the right.  Select the person of interest.  
• In the data returned, the GT Account Username will in the person's "IM" value.  It will be "sip:[gt account]@gatech.edu".

Using Command Line tools

Note: Any command line tools to query data via the Georgia Tech "White Pages" (which both the Georgia Tech Directory Tools and the 'ldapsearch' examples use) will only work from on-campus or over the campus VPN.

• Georgia Tech Directory Tools [Tip from Shawn Carnley]
• UNIX 'ldapsearch' Command Line Query [Code Included]

If you have enabled CAS authentication to help keep your site secure, but have a limited number of non-GT users who need access to certain protected features of your Drupal site, you can create guest GT Account Usernames for them.

Creating a New Guest User Account

1. Log into PASSPORT (https://passport.gatech.edu)
2. Under Sponsored Guests, choose Manage guests.
3. Select the Create a new guest button and follow the instructions to create your guest user.
   • Only grant LAWN wireless or T-Square access if necessary.
   • Only grant permissions for the length of time the guest will need access (1-365 days).
4. Write down the Guest's new GT Account Username and Password, so you can communicate it to them over the phone or in person (since it's not very safe to send passwords electronically).

If you are unable to log in with CAS after migrating a site, make sure you copied the .htaccess file in the root of your site (httpdocs on OIT Web Hosting). 

Please note that this file may be hidden to some file browsers. If so, configure your file browser to show hidden files.

Technical Details

CAS requires that Clean URLs be enabled. When Clean URLs is enabled, Drupal edits the .htaccess file to properly handle normal-looking URLs. 

When a Drupal website is migrated without the .htaccess file, Drupal reverts to the ugly URL schema (i.e. http://drupal.gatech.edu?q=user/login). This has the side-effect of also disallowing CAS from working properly.

Setting up a private filesystem requires some under-the-hood configuration, so the following is recommended only for someone who already understands filesystems and editing configuration files.

These instructions are tailored for the OIT Web Hosting Plesk servers, but can be adapted to other configurations. Instructions are based on using the Plesk GUI, but you can also accomplish all of the Plesk related steps from an SSH connection if you are more comfortable in a command line environment.

Configuration

1. Connect to your hosting account's Plesk console.

2. Go to the File Manager

3. Create a new subdirectory for your private files

   1. On the first File Manager screen, select Home Directory to move to your hosting account's home directory.

   2. Select the blue "+" button to the left of the "Copy", "Move", "Archive", etc. buttons, and select Create Directory.

   3. Give your new directory a suitable name (these instructions will call it "files-private").

4. Edit your site's settings.php file

   1. In File Manager, navigate into httpdocs/sites/default

   2. Find "settings.php" and use the drop-down selection at the right end of the line to Change Permissions.  Give "Owner" the "Write" permission and save.

   3. Use the drop-down on the "settings.php" line to Edit in Code Editor

   4. Search for "Private file path" and read the instructions there.

   5. Uncomment the line of code that sets the "file_private_path" value, and fill in the value like so: /var/www/vhosts/mysite.gatech.edu/files-private

      • Important: "mysite.gatech.edu" should be replaced with your hosting account ID, which is the domain name shown when you first open your Plesk control panel - this may not always be the domain name you normally use to access your site.  Also, "files-private" should be the directory you created in step 3 above.

5. Save your changes, then open a new browser window, log into your site as an administrator, and clear all of the caches.

6. Go to the site Status Report (administrative toolbar -> Reports -> Status report and make sure there are no errors.  Also go to Reports -> Recent log messages and look for any error or warning messages there.

If all looks good, then move on to the next section.  Otherwise, troubleshoot any problems first.

Create a Private Attachments Field

1. While logged into your site as an administrator, go to Structure -> Content types -> Basic page -> Manage fields

2. Create a new field of type File and call it something like "Secure Attachments" or "Private Attachments" to distinguish it from the existing "Attachments" field.  Specify a subdirectory value like "campusonly" (or perhaps "campusonly/[date:custom:Y]-[date:custom:m]" if you want files organized in further subdirectories based on the month they were uploaded).  Configure the rest of the field as you wish, making sure you set the file size limit and allowed file extensions to meet your needs.

3. If you are going to apply any kind of access restrictions to some or all of your private filesystem, then you will need to know the system path you want to protect, which is different from the path you put into the settings.php file earilier.

   1. The base system path for the private filesystem in Drupal is "/system/files".  Adding any rules for this base path will restrict all private files in all use cases, which may be more than you need.

   2. When you created your Secure Attachments field, you specified a subdirectory.  To protect just the files connected to that field, add the subdirectory to the base path to get the full system path for that subdirectory (e.g. "/system/files/campusonly")  Adding rules for this path will only protect files in the "/campusonly" subdirectory of the private filesystem while ignoring all other private files.

A Drupal module called Access Filter combined with a private filesystem can be used to limit file access to campus and VPN IPs only.  For most cases, that's just as good as using forced logins via CAS authentication without the headaches of having a user account created on your Drupal site for every person who accesses one of your protected pages or files.

Important: Drupal access control modules will only work with a private filesystem, as Drupal does not actually handle access requests for files uploaded to public file fields (it lets Apache handle those requests for maximum speed).  If you do not already have a private filesystem set up, you will need to configure your site to use a private filesystem.

Instructions for Installing and Configuring Access Filter

1. Configure your site with a private filesystem and make sure it is working correctly.

2. Install the Access Filter module like you would any other Drupal module.

3. Once you have the module installed, go to the Administrative Toolbar, to Configuration -> People -> Access filters and create a new filter with the following components:

   Conditions:
   - { type: path, path: /system/files/campusonly/* }
   
   Rules: 
   - { type: ip, action: deny, address: '*' }
   - { type: ip, action: allow, address: 130.207.0.0/16 }
   - { type: ip, action: allow, address: 128.161.0.0/16 }
   - { type: ip, action: allow, address: 143.215.0.0/16 }
   - { type: ip, action: allow, address: 192.93.8.0/24 }
   - { type: ip, action: allow, address: 10.0.0.0/8 }
   - { type: ip, action: allow, address: 172.16.0.0/12 }
   - { type: ip, action: allow, address: 100.64.0.0/10 }
   
   Repsonse Code:
   302
   
   Redirect URL:
   /campusonly

   Make sure that path in the condition matches up with the path that your Secure File field is using, so that the rule will apply to all files uploaded to that field.

4. Finally, make a generic page at the path "/campusonly" that will tell outside users that the content they're trying to access is available on-campus or via the VPN only.

Now, any regular content manager can simply upload campus-only files to the Secure File field (created when setting up a private filesystem) on the related page and then link to the file like they would do for a normal file attachment. When accessed from on-campus or the VPN, the user simply gets the file. When accessed from off-campus, the user gets redirected to that /campusonly page.

A number of performance settings are recommended to cache Drupal data objects and speed up your site.

Enable Caching and Aggragation Settings

These settings can be enabled in Drupal 7 via the administrative control panel under Configuration -> Development -> Performance

• Cache pages for anonymous users
• Cache blocks
• Compress cached pages
• Aggregate and compress CSS files
• Aggregate JavaScript files
• Set Minimum cache lifetime = 15 minutes

Disable and Remove Unnecessary Modules

Additional Optimization Techniques

There are also quite a few modules that attempt to cache resource-heavy actions on Drupal.

Getting Started with Performance Module

For most websites, core Drupal caching should be sufficient to keep CPU/memory usage down and keep your website running smoothly. However, for larger and more complex websites, additional caching and optimization will be needed.

For your specific website (and its use cases, structure, and workflows), please browse through the modules below and see which module(s) may work for your website. 

Advanced CSS/JS Aggregation

Availability: Drupal 7, Drupal 10

From the module's Drupal.org page:  AdvAgg allows you to improve the frontend performance of your site. The performance benefits are achieved by using some of the features found in AdvAgg and its sub modules. Out of the box AdvAgg's frontend performance will be similar to cores.

Boost

Availability: Drupal 7

Boost provides static page caching for Drupal enabling a very significant performance and scalability boost for sites that receive mostly anonymous traffic.  For shared hosting this is your best option in terms of improving performance.

• Boost is not recommended for large websites (nodes >= 1000), as the caching process will take up the websites' allotment of CPU cycles. This will slow down the website to be unusable for end-users.
• Boost can be used alongside Memcache API and Integration
• No configuration for Boost is necessary beyond installing and enabling the module. 
• Core caching in Drupal must be disabled for Boost to work properly

CDN

Availability: Drupal 7, Drupal 10

CDN provides easy Content Delivery Network integration for Drupal sites. It alters file URLs, so that files are downloaded from a CDN instead of your web server.

Before you begin, you will need to select a CDN provider. CDN have different costs and features depending on your needs. 

• These CDNs are currently used on campus:
  • Keycdn.com - Used by the Office of International Education (Jimmy Kriigel)
    • http://oie.gatech.edu
    • http://pacific.gatech.edu
    • http://oxford.gatech.edu
• This module is best used for websites with lots of traffic and lots of images and/or locally hosted videos.
• KeyCDN has made a CDN Drupal Integration Tutorial available.
• The CDN module has TEST Mode.  If you don't want to use the CDN to serve files to your visitors yet, but you do want to see if it's working well for your site, then enable testing mode.  Users will only get the files from the CDN if they have the permission to "Access files on CDN when in testing mode".
• The "Far Future expiration" option doesn't work with the IMCE module.
  • Update: IMCE has a patch in their dev branch for this issue.
• You can manually flush a CDN cache file by having the Display statistics Shows enabled and scrolling down to the bottom of the page and selecting "Touch" to purge the file.

Entity Cache

Availability: Drupal 7

From the module's Drupal.org page:  Entity cache puts core entities into Drupal's cache API.  Due to the entity loading changes in Drupal 7, no core patches are required.

Don't bother using this module if you're not also going to use Memcache API and Integration or Redis – the purpose of Entity Cache is to allow queries to be offloaded from the database onto alternative storage, and there are minimal, if any, gains from using it with the default database cache.

Memcache API and Integration

Availability: Drupal 7

This module provides integration between Drupal and Memcached with the following features:

• An API for using Memcached and the PECL Memcache or Memcached libraries with Drupal.
• Memcache backends for the following systems (all drop-in):
  • Caching (memcache.inc)
  • Locking (memcache-lock.inc)
  • Sessions (memcache-session.inc) (D6 only)
• A module that provides a comprehensive administrative overview of Drupal's interaction with Memcached and stats.
• A set of tests that can be run to test your memcache setup.

Memcache is ideal when there are lots of database reads and writes, as it is a cache for the data layer (this is also why it can so easily whitescreen your site when things go wrong). This article does a decent job of explaining the "whens" and "whys" of APC, Varnish and Memcached.

Recommended Settings

After enabling the memcache module, add this text to the bottom of your settings.php:

$conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
$conf['lock_inc'] = 'sites/all/modules/memcache/memcache-lock.inc';
$conf['memcache_stampede_protection'] = TRUE;
$conf['cache_default_class'] = 'MemCacheDrupal';
$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
$conf['page_cache_without_database'] = TRUE;
$conf['page_cache_invoke_hooks'] = FALSE;
$conf['memcache_servers'] = array('localhost:11211' => 'default');

You will need to adjust the module directories if your module is installed in a different directory.

Troubleshooting

In some cases, Drupal will white-screen after settings.php is edited to reflect the new memcache settings. If this occurs, please check your error log on Web Hosting.  If you see a 'Fatal Error', follow the directions below (taken from this Drupal.org thread):

1. Backup your website.
2. Download registry_rebuild and upload to sites/all/modules.
3. Run registry_rebuild by navigating your browser to: [yourdomain]/sites/all/modules/registry_rebuild/registry_rebuild.php
4. If no errors show up, your registry has been rebuilt.
5. Delete the module from the sites/all/modules directory.

Varnish HTTP Accelerator

Availability: Drupal 7

Varnish HTTP Accelerator provides integration between your Drupal site and the Varnish Cache, an advanced and very fast reverse-proxy system.  Basically, Varnish handles serving static files and anonymous page-views for your site much faster and at higher volumes than Apache, in the neighborhood of 3000 requests per second.

Besides performance modules, there are several other methods for increasing the performance of your Drupal site.

Disable Modules Only Needed During Development

Only enable these modules while actively developing, and then turn them off the rest of the time.

• Field UI (in core)
• Rules UI/Admin
• Views UI
• Module Filter
• Advanced Help
• Fast Permissions Administration
• Devel

Track Your Site's Performance Baselines

• Drupal's Devel module
  • Execution time and memory usage
  • Query logging
• Web optimization
  • SpriteMe
• Web testing
  • webpagetest.org
  • Google's PageSpeed Online
• Browser-based
  • Firebug or Web Inspector
  • YSlow!
• Saas products
  • New Relic
  • Yottaa

Locate and Fix PHP Errors/Warnings

• Turn on verbose error reporting to find errors and warnings (check Apache error logs as well)
• Perform performance testing of any custom coding.

Optimize Javascript and Other Front-End Features

• Example modules using JavaScript:  Views Slideshow and Conditional Fields.

Unless you manually configure Drupal cron to be run by your web hosting server, it will be automatically run when someone visits a page on your Drupal site after a certain amount of time has passed.  This method works perfectly fine, but can slow down the display of the page the user requested since the cron run will block page generation until it has finished.  This becomes more noticeable on site visited less frequently as more tasks can accumulate that need to be executed during a cron run.

To keep this from happening, you can schedule Drupal cron to run automatically in the background.  On a web server that you fully control, you can use UNIX style cron to run the Drupal cron job.  You can also do this on OIT Web Hosting, but you have to configure the job via the Plesk Control Panel.

Step by Step Instructions

1. Log into your hosting account's Plesk control panel.
2. On the main control panel page, navigate to Schedule Tasks, found in the right-hand sidebar menu.
3. On the Scheduled Tasks page, select the Add button
4. Fill out the form as follows (the example here will set up Drupal cron to run every eight hours):
   • Minute: 0
   • Hour: 0,8,16
   • Day of the Month / Month / Day of the Week: * (insert an asterisk)
   • In the text field, Command, enter the following:

     curl --silent --compressed http://YOURDRUPALSITE.gatech.edu/cron.php?KEY-FROM-ADMIN-REPORTS-STATUS-PAGE

     You can find the link to put at the end of this command (KEY-FROM-ADMIN-REPORTS-STATUS-PAGE) on your Drupal site's status report page at Reports -> Status report (admin/reports/status)

Video Tutorial

Play Video

Logging details about your site's usage can be very valuable, but if not configured properly, can also be a huge resource drain.  The following articles provide useful best practices for managing your Drupal site's logging functions.

Logs and Logging Guides and Resources

Georgia Tech staff, students, and faculty can now use a Georgia Tech instance of GitHub, a version/revision control system.  This service is available thanks to the College of Engineering's brilliant proof of concept with GitHub Enterprise, and the ensuing excited buy-in from the Office of Information Technology.

What is GitHub and Why Should I Use Revision Control?

GitHub is a proprietary hosted extension of the open-source Git version/revision control system commonly used for open-source software projects.  It is very useful for multi-developer projects, as it allows coordinating and tracking code changes and the orderly acceptance and integration of those changes into the master project.  Version control also makes it much easier to revert back to an earlier version of the software if it is discovered that accepted changes have caused unexpected problems.

Or, to put it short, it'll save your bacon.  Figuratively, not literally.

Support Policy

OIT does not offer technical support or training for Git or GitHub usage.  If you want to learn how to use git, see below for many educational resources.

Accessing Georgia Tech GitHub Enterprise

Just go to https://github.gatech.edu and log in with your GT Account Username and password.

GitHub User Software

You can access repositories in GitHub using git from the command line of most Unix based operating systems (see GitHub's KB), but you can also use a variety of GUI (graphical user interface) applications, such as:

• For beginners, GitHub's Desktop (for Mac OS X or Windows).
• For something that works on both Windows and Mac, try SourceTree.
• There are also lots more graphical clients to use with git.

Drupal List

We have a Drupal community group in GitHub that allows users to share and collaborate on projects. Please add collaborative projects to the GT Drupal group on GitHub at Georgia Tech.

Learn to Use git with GitHub Resources

You can learn how to use git (and GitHub) with these tools from GitHub Enterprise, such as:

• Guides: Tutorials, tips, and workflows to help you and your team learn about GitHub.
• Reference Sheets: Quick reference guides and manuals for GitHub 

Learn to Use git with General Internet Resources

The internet has lots of other great places to teach you about git. Here are a few:

• Lynda.com - GitHub for Web Designers
• Lynda.com - Fundamentals of Software Revision Control 
• Learn Git Branching - A good interactive visual guide to Git's concept of version control.

Local GitHub Guides and Resources

Drush (Drupal Shell) is a great Drupal "module" to accomplish many administrative tasks via the command-line. It is not a module in the normal sense, because it's not enabled/disabled from the Drupal admin. Instead, it actually lives anywhere on your local system and is run like any other local executable. Here are some of its key features from the Drush Drupal.org page:

A few core drush features:

• The Drush Package Manager allows you to download, enable, disable, uninstall, update modules/themes/profiles/translations from the command line in a very simple way (apt-get style) - just type e.g. drush dl views and drush enable views in a Drupal directory to install the Views project!
• Additionally, the Drush Package Manager also allows you to update all your modules with just one command - drush update.
• Drush Core: several useful utilities for site administrators and developers (e.g. drush cron or drush cache clear)
• Drupal SQL Commands help you issue queries to any of your databases (i.e. is multi-site aware) and even helps you migrate databases between your environments.
• Drush simpletest commands make it easy to run unit tests from the command line and email results to your dev team.
• Drush now supports aliases which let's you perform actions on separate Drupal installations.  This is very useful for multi-site configurations.

Drush Guides and Resources

Creating a new MySQL database for a site hosted on OIT Web Hosting can be a little confusing.  Below are the steps for getting a database set up and configured properly via the Web Hosting Plesk control panel, as well as generic steps for creating a new database on any MySQL instance that has phpMyAdmin installed.

MySQL Database Creation on OIT Web Hosting

1. Visit OIT Web Hosting [https://hosting.gatech.edu/] and select the website you want to work with from the list of sites that you manage.
2. Select the Databases management link.
3. On the Databases management page, select the Add New Database link.
4. Fill in the fields on the Add New Database form, and be sure to copy down everything for future reference.  Use the password generate to generate a secure password (select the 'Show' button to see the generated value so that you can copy it down.)
5. Select the OK button to create your new database.
6. Back on the Databases management page, you should see a listing in the table for your new database.  The Webadmin link on that row will let you access your database via phpMyAdmin.

Video Tutorial (1:13)

Play Video

MySQL Database Creation on a Standard Apache HTTPD Server Via phpMyAdmin

1. Log into phpMyAdmin on your server with the master (root) user account for your mySQL instance.
2. Select the Databases tab.
3. In the box under Create database, enter the name for your new database and select the Create button.
4. Select the Users tab and create a new user with a unique name and password.  Be sure to write down the name of the database you create, as well as the username and password you make for it. (As always, try to choose a fairly-secure database username and password and do NOT use your GTaccount - jdoe3).
5. Once the account is created, grant it access to the database that you created.  You'll probably want to give the account all privileges for the database except "grant", as you usually don't want the account to be able to give out access to other accounts.

Video Tutorial (0:39)

Play Video

You can view any MySQL database on an OIT Web Hosting website using many different GUI based applications. Below are a few implementations that have been used by members of our community:

General Instructions

OIT has an FAQ entry explaining how to connect to your hosting database, which also discusses using phpMyAdmin to view your database(s) from your hosting control panel (which doesn't require any additional software).

Rochester University has a nice tutorial on using phpMyAdmin with MySQL.

Elsewhere in this handbook is a  more in-depth post on SSH tunneling.

The general information you'll need, if you choose to connect with a more graphical software application, is:

• the domain name of the site your database uses (example: mydepartment.gatech.edu)
• the SSH or FTP Login account name and password for this site
• the host your database lives on: for OIT Web Hosting, use "mysql.localhost" instead of plain "localhost".
• the database account's username and password (this will be different from the SSH/FTP login account and password)
• the port for your database: 3306

MySQL Workbench

Andrew Dugenskei (a member of the GT Drupal community) has a preference for MySQL Workbench.

Fortunately, MySQL Workbench (available for Mac OSX and Windows) makes it very easy to communicate with OIT web hosted databases and it is free. If you're on campus, no other software is needed. If you're off campus, you just need to first make sure you are connected to the VPN.

Below is a screen capture from the Workbench connection manager with some pseudo values. Once the correct values are entered, connecting to an OIT databases is a just a click away.

From the above screen capture and based on the Workbench Installation Guide, you can use these settings.

Under the Connection Tab, Choose "Standard TCP/IP over SSH" and then enter these parameters for your site:

• SSH Hostname: mydepartment.gatech.edu (port name ":22" at end is optional)
• SSH Username: myFTPaccount (for your SSH or "Local FTP" account on Web Hosting)
• SSH Password: myFTPpassword (for your SSH or "Local FTP" account on Web Hosting)
• MySQL Hostname: mysql.localhost (for web hosting, just use this instead of worrying about which server you're on)
• MySQL Server Port (leave same): 3306
• Username: database_user (for this database only)
• Password: database_password (for this database only)
• Default Schema: leave blank

Navicat (Mac, Windows, Linux)

Mike Alberghini (a member of the GT Drupal community) has a preference for Navicat because the software:

• Has a good GUI
• Handles multiple databases well,
• Has Mac OS X support
• Is 40% off for educational users
• Saves connection info for ssh tunnels and start them as needed to connect to servers

Screenshots of a successful Web hosting database connection with Navicat are below. 

For Navicat, use the following settings on the "General" tab:

• Connection Name = My Department Site
• Hostname/IP Address = mysql.localhost (this is important for you to connect to Web Hosting)
• Port (leave same) = 3306
• User name = This is the username for your DATABASE's user.
• Password = This is the password for your DATABASE's user.

To finish your connection with Navicat, use the following settings on the "SSH" tab:

• Use SSH tunnel = check YES
• Hostname/IP Address = mydepartment.gatech.edu
• Port (leave same) = 22
• Username = This is the username of the web hosting FTP account for this site.
• password = This is the password for the web hosting FTP account for this site.

Sequel Pro (Mac)

Adam Arrowood (a member of the GT Drupal community) has a preference for Sequel Pro because the product:

• Has a nice GUI, ssh tunneling, etc. as found in other similar products.
• Runs (only) on Mac OS X.
• Is a free product.

Drupal 7 began forcing mySQL to act like a traditional SQL server so that all SQL code used in Drupal will be highly compatible with other database systems like PostgreSQL or SQLite. This means that mySQL statements that syntactically work in other contexts may produce errors under Drupal 7 or 9. Drupal 8+ adds the 'ONLY_FULL_GROUP_BY' restriction, which can potentially cause custom mySQL code that worked in Drupal 7 to fail with errors in Drupal 8+.

Here's the exact settings being used in Drupal 8:

• SET sql_mode = 'ANSI, STRICT_TRANS_TABLES, STRICT_ALL_TABLES, NO_ZERO_IN_DATE, NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO, NO_AUTO_CREATE_USER, ONLY_FULL_GROUP_BY'

The mySQL Reference Guide has full details on these SQL modes and their effects. (See especially the section on STRICT mode and ONLY_FULL_GROUP_BY mode.)

A shell script that prints out a list of enabled modules in all accessible databases, designed for ssh use when you need to check multiple Drupal 6 or 7 databases at one time.

Editor's Note:  A similar concept would work just as well for Drupal 8, but the database table names and structures have changed in Drupal 8, so you would need to adjust the script accordingly.  Also, be aware that this script will not work on any Drupal instance where you have used a custom table prefix for all of your Drupal site tables.

With thanks to Abdul Manaf on DBA.stackexchange for the basic code.

# mysql credential
user="root"
pass="pwd"

all_dbs="$(mysql -u $user -p$pass -Bse 'show databases')"        

# Exclude databases you don't want to check, such as non-Drupal 6 or 7 dbs.
# Then output database name and an alphabetized list of Enabled modules.
for db in $all_dbs
     do
        if [[ "$db" != "information_schema" &&
            "$db" != "mysql" &&
            "$db" != "performance_schema" &&
            "$db" != "test" ]] ; then
            echo '====================='
            echo "DATABASE: $db (ENABLED Modules)"
            echo "---------------------------"
            mysql -u$user -p$pass $db -sN -e "SELECT name FROM system WHERE status = 1 AND type = 'module' ORDER BY name ASC;" 
        fi 
     done

Below is SQL code that prints out SQL statements that you can copy and paste back into phpMyAdmin (or any MySQL management tool that can connect to your Drupal database).  These statements will help you get a list of enabled modules, when you need to check multiple Drupal 6 or 7 databases at one time.

With thanks to Aaron Brown on DBA.stackexchange for the basic code.

Be careful to copy the backquotes/backticks (that look a little like left-leaning apostrophes) exactly.

SELECT CONCAT('SELECT \`name\` FROM ', schema_name, '.\`system\` WHERE \`status\` =\'1\' AND \`type\` =\'module\' ORDER BY \`name\` ASC;')
FROM information_schema.schemata
WHERE schema_name NOT IN ('information_schema','mysql','performance_schema','test', 'excluded_database');

This will print out a series of SQL statements, like the one below, which you could paste into the SQL tab of phpmyAdmin, in order to create lists of enabled modules.  This can be helpful if you don't have ssh access to your site, but still want an easy way to get a simple text list of enabled modules.

SELECT `name` FROM ms6_sample1.`system` WHERE `status` ='1' AND `type` ='module' ORDER BY `name` ASC; SELECT `name` FROM ms7_sample2.`system` WHERE `status` ='1' AND `type` ='module' ORDER BY `name` ASC;

Issue

Email from a Drupal website on OIT Web Hosting is being delivered to non-Georgia Tech email addresses, but is failing on Georgia Tech email addresses (@gatech.edu).

Solution

To fix this issue, ensure that the From: email address in Drupal (set in Configuration -> Site Information) is a valid Georgia Tech email address.

More details, per OIT Web Hosting:

Since this problem has come up more frequently, I’ll clarify what the issue is:

outbound.gatech.edu requires that if you are sending to *@*.gatech.edu address that the OIT MX servers handle (which is most of them), the “From:” address has to be a valid Georgia Tech address. Along with this, if the “From:” address isn’t valid, there is no way for outbound.gatech.edu to send a bounce message back.

This is a requirement of the OIT MX servers and isn’t related to anything that Web Hosting restricts.  In fact, on the Web Hosting servers, the message shows as sent, but that just means it was sent on to outbound.gatech.edu.

Issue

You've upgraded your Drupal 8 site to 8.8+ and now get the following warning in your site's Status Report.

Deprecated configuration
You are using deprecated configuration for the temporary files path. Your temporary directory configuration
matches the OS default and can be safely removed.

Cause

Drupal 8.8 changed some of the configuration handling for the temporary file path, moving storage of that path into a config system key.  However, that key is not directly editable, and under certain odd circumstances can get populated with the default system temporary directory path.

Solution

Warning: the following is minimally tested, and while it seems to work, be cautious and consider testing on a copy of your site first.  At a minimum, back up your database before trying this to be safe.

Putting the following into a module file temporarily and pulling up any page in the site should clear the value of the config key:

\Drupal::service('config.factory') -> getEditable('system.file') -> clear('path.temporary') -> save();

If the warning message then disappears from your Status Report, you can remove the above line from wherever you put it.

Issue

Below is a quick summary of what you need to do if you are changing your Drupal site's host name / domain name without moving it to a new web hosting location.

If you are moving the site to another location, then you'll also need to see the Site Migration section for additional guides.

Solution

1. First, go ahead and request that your new host name be created in DNS and pointed to your existing web server.  You'll need to know the host name and/or IP address of your existing server to provide to your DNS administrator.  If you don't know either, then provide the current host name for your website, and your DNS administrator should be able to determine the web server hostname and IP address from it.

2. Configure your web server to recognize the new host name.  If you are using an automated web hosting solution like OIT's Web Hosting, then go into your control panel and add the new host name as a domain alias for your hosting account.

3. Check your site for links hard coded to your old host name:
   • The quickest way of doing this (though it does require some advanced knowledge) is to dump your database out to an SQL file and do a search through that file for instances of your old host name and then identify the pages that need to be updated.  
   • Alternatively, you could go through every page, opening each one up for editing, and check the page source for every inline link and every inline image.  

   If you don't fix these links, then users will be silently switched over to the old hostname when they follow those hard coded links, and when you eventually delete the old hostname from DNS, those links will simply break.

4. If you want to force everyone to view your site through the new host name (which is important for Search Engine Optimization), you can add something like the following to your .htaccess file, where oldsitename.gatech.edu and newsitename.gatech.edu are replaced with the appropriate values:

     RewriteCond %{HTTP_HOST} ^oldsitename.gatech.edu [NC]
     RewriteRule ^ http%{ENV:protossl}://newsitename.gatech.edu%{REQUEST_URI} [L,R=301]
   

As announced by the Office of Information Technology on 2/4/2021:

We would like to inform you of changes to Identity & Access Management’s plan to upgrade Single Sign-On (SSO) services CAS 6. The CAS upgrade includes an upgrade from CAS 3 to CAS 6, merges CAS and Shibboleth/SAML2 SSO services, and improves the SSO service’s availability, security, and sustainability. Unlike the original plan, which involved a single upgrade window, this upgrade will occur in phases over the next several weeks to allow application owners to appropriately test, prepare, and upgrade in phases.

In order to streamline this process and avoid downtime, service owners are asked to test their applications against the new version throughout this process to make sure your applications remain compatible.

Remainder of post copied at the end of this page

If you are running a Drupal site that uses GT Account Username authentication (also known as CAS authentication), then you should know the following:

• A CAS 6 server has been set up and is available at sso.gatech.edu .  You can start testing against this server if you wish.

• If your Drupal site is running Drupal 8 or Drupal 9, you do not have to do anything (but see the warning below).

• If your Drupal site is running Drupal 7 or earlier, you should make sure you are on the latest version of phpCAS (currently 1.3.8).

• Warning: If you do not update your configuration to point to sso.gatech.edu, your site editors will have to log in a second time to access your site during Phase 3 (see below for exact dates), and will receive a warning that your site is still using the legacy authentication server.  If you don't mind this happening for a period of about one month, the warnings will go away at the start of Phase 4, when the old authentication server address will be automatically redirected to sso.gatech.edu

• To update your site to point to sso.gatech.edu:

  • For Drupal 8 or 9:

    1. Go to the CAS configuration page on the black administration toolbar under Configuration -> People -> CAS ; alternatively, you can access the configuration page by adding "/admin/config/people/cas" to the end of your site's front page URL.

    2. Under CAS Protocol version, select 3.0 or higher

    3. Under Hostname, enter "sso.gatech.edu" (without the quotes).

    4. If you want to check the rest of your settings, see our Drupal 8/9 CAS Configuration Page.

    5. Don't forget to scroll down and Save configuration.

  • For Drupal 7:

    1. Go to the CAS configuration page on the black administration toolbar under Configuration -> People -> CAS settings ; alternatively, you can access the configuration page by adding "/admin/config/people/cas" to the end of your site's front page URL.

    2. Under Version, select 3.0 or higher

    3. Under Hostname, enter "sso.gatech.edu" (without the quotes).

    4. If you want to check the rest of your settings, see our Drupal 7 CAS Configuration Page.

    5. Don't forget to scroll down and Save configuration.

Remainder of original OIT post about CAS upgrades:

The schedule and impact for each phase is as follows:

Phase 1: Wednesday, February 10 – No Impact

Sso.gatech.edu will be launched as a new production instance of CAS 6. No action is required. Application owners should begin migrating or plan migration to the new system after this date. Testing is also encouraged to ensure that the migration will be successful.

Phase 2: Wednesday, February 17 – Possible Impact to Shibboleth Applications

Shibboleth/SAML2 applications (those that use idp.gatech.edu for logins) will transition to the new instance of CAS 6. Login sessions will be shared between CAS 6 and CAS even if application systems have not been upgraded. At this point, all application owners should be in the process of migrating to the new system. Testing is also encouraged to ensure that the migration will be successful.

Phase 3: Thursday, March 11– Impact to Any Applications that have not Upgraded

CAS 6 login sessions will no longer be shared with CAS. Users of applications that have not been migrated to CAS 6 will see warnings that they are using a deprecated login system and that the application should upgrade to sso.gatech.edu by Wednesday, April 21 or risk login problems. Application owners should continue migrating to the new system. Testing is also encouraged to ensure that the migration will be successful.

Phase 4: Wednesday, April 21 – Impact to Any Applications that have not Upgraded

At this phase, most applications should be upgraded to CAS 6. All remaining applications will automatically be upgraded. Login.gatech.edu will begin automatically redirecting to sso.gatech.edu.

Please note that CAS, SAML1, SAML2, Shibboleth, and ADFS will be affected by this upgrade. During the final phase (Wednesday, April 21), visits to login.gatech.edu will be automatically redirected to the new system at sso.gatech.edu.

Throughout the duration of this upgrade, application owners will receive regular communications including weekly updates surrounding each phase and ongoing reports to show the status of application upgrades. You will also receive a calendar invite from the IAM team shortly after receiving this message inviting you to weekly work sessions/open office hours for assistance with upgrading systems. Finally, "open mic" Teams sessions are scheduled during the change windows for instant collaboration between application owners, users, and the IAM team.

For additional information about this upgrade, using your VPN, please visit http://b.gatech.edu/CAS6-upgrade or contact Nadeem Rizvi at nrizvi@gatech.edu.