Pantheon setup

Pantheon’s standard approach to building Drupal sites is called Integrated Composer. This workflow provides a way to assemble external code during deployment from a list of dependencies defined in the site. Pantheon’s documentation succinctly summarizes this approach:

Composer encourages a mental model where code not written specifically for a given project is a dependency. Only files unique to the project are tracked as part of the project’s main source repository, also referred to as the canonical site repository.

With Integrated Composer, a new Drupal Kit site can be created entirely through the Pantheon dashboard.

Creating a new site

  1. Request access to the University of Texas organization (see https://ut.service-now.com/sp?id=kb_article&number=KB0014813).

  2. Sign in at https://dashboard.pantheon.io/login

  3. Use this link to create a new UT Drupal Kit site: https://dashboard.pantheon.io/sites/create?upstream_id=f0de5643-e2ce-4614-8fc0-c555634219bc

  • Enter a name for the site.

  • Use “United States” for the region. Click Continue.

Important

After you click Continue, it will take several minutes for the platform to set everything up. You can confirm the platform is set up by checking that the Workflow button shows no in-progress processes. Attempting to visit the site while processes are still running can cause the site to malfunction.

  1. Still in the Dev tab, click Visit Development Site and follow the prompts to complete the CMS installation.

For local development, return to the Dev tab, set the site’s Development Mode to Git, and clone the site locally. Then, in your local terminal, from the project root directory, run composer install.

Anatomy of the Pantheon codebase

Your Pantheon dashboard’s DEV tab includes a button to “Clone with Git” for local development. Doing so will show a codebase that consists, in its entirety, of the following:

├── .editorconfig
├── .gitignore
├── COPYRIGHT.txt
├── LICENSE
├── README.md
├── composer.json
├── composer.lock
├── config
│   └── .htaccess
├── pantheon.upstream.yml
├── upstream-configuration
│   ├── composer.json
│   └── scripts
│       └── ComposerScripts.php
└── web
    └── sites
        └── default
            └── settings.php

Note that the site repository does not contain any of the actual files related to Drupal core or the custom theme and modules provided by the UT Drupal Kit. These elements are pulled in via Composer during each code deployment process on Pantheon. See Integrated Composer for more details about Composer on Pantheon.

Your codebase includes a connection to the Pantheon “upstream.” The upstream supplies the UT Drupal Kit code and sets which version of the Kit your site is using. This means that some files in your codebase should not be directly modified; when you use the Pantheon dashboard to apply UT Drupal Kit updates, these files will be updated by the upstream repository. The following table should be used as a reference for which files should not be modified:

File

Safe to change?

Notes

.gitignore

Yes

Directs certain files or directories not to be committed to a Git repository. Generally speaking, developers should not have to modify this file for use with Pantheon sites, but it can be used as needed per standard Git methodology.

.editorconfig

Yes

Default code editing configuration settings. These may be changed or removed by individual sites without consequence.

composer.json

Yes

Developers can use standard Composer commands to manage site specific dependencies and configuration.

composer.lock

No

This file should not be directly modified. It contains metadata about requirements.

config/

Yes

If you decide to use Configuration Management, your site configuration can be stored here.

pantheon.upstream.yml

No

Defines default values for site settings such as PHP version and HTTPS enforcement. It should not be directly modified. If you need to override these values, you should add a pantheon.yml file.

settings.php

No

Unlike a typical Drupal site, this file is reserved for ITS to push settings changes to sites. Your settings should go in a settings.site.php file.

upstream-configuration/

No

Local repository of the information related to the UT Drupal Kit. It should not be directly modified. Changes to the UT Drupal Kit will appear here will new releases are available, and those changes can be applied via the Pantheon dashboard.

Further reading

For more information on what is included in this scaffolding and how it is designed to work, see the following topics:

Integrating Enterprise Authentication

By default, site accounts leverage a local username/password combination for authentication. Sites may switch to EID authentication using the university’s Enterprise Authentication system.

This requires the Drupal Kit team to configure Security Assertion Markup Language (SAML) metadata for the site. This process is described below.

Request integration

  1. Confirm the site is updated to Drupal Kit version 3.23.0 or higher.

  2. Complete the Pantheon SAML Integration request form.

  3. Wait to receive confirmation from our team that the integration work on our end is complete.

  4. In the Drupal site, enable the “UTexas SAML Auth Helper” and “SAML Auth” modules at Admin > Extend (/admin/modules) or via terminus drush <site>.<env> -- en utexas_saml_auth_helper samlauth.

  5. If you have not already done so, go to People > Add User (/admin/people/create) and create an account with EID as the username.

  6. Test authentication by going to yoursite.utexas.edu/saml/login and verifying the university’s Enterprise Authentication sign-in screen is provided, and that successful authentication signs in the user account in the Drupal site.

Switch from an existing SimpleSAMLphp integration to OneLogin

  1. Confirm the site is updated to Drupal Kit version 3.23.0 or higher.

  2. In the Drupal site, uninstall the “SimpleSAMLphp Auth” module at Admin > Extend > Uninstall (/admin/modules/uninstall) or via terminus drush <site>.<env> -- pmu simplesamlphp_auth.

  3. In the Drupal site, enable the “UTexas SAML Auth Helper” and “SAML Auth” modules at Admin > Extend (/admin/modules) or via terminus drush <site>.<env> -- en utexas_saml_auth_helper samlauth.

  4. Test the new integration by going to your.pantheonsite.io/saml/login and verifying the university’s Enterprise Authentication sign-in screen is provided, and that successful authentication signs in the user account in the Drupal site.

  5. Remove the legacy integration from your codebase:

composer remove utexas/pantheon_saml_integration

  1. Commit this change to the repository, push to the Pantheon remote, and deploy to Test and Live.