Concepts and tools

When compared with previous versions, development with the latest version of Drupal requires the use of several concepts and tools that may be new to web developers.

Composer

The Drupal Kit requires use of Composer for installation and updates. Composer is a tool for managing PHP dependencies, where the developer specifies what version of each external library is needed. Composer manages the process of downloading and installing the libraries.

The following visualization demonstrates how a typical Drupal Kit site will define top-level dependencies in the root composer.json. It shows how the “kernel” of the Drupal Kit, and Drupal core itself, are defined in a separate upstream-configuration location.

Click the visualization for more detail.

Visualization of nested Composer dependencies

Composer references

Version control

While not strictly required, the use of a version control system such as Git is strongly recommended as a best practice for developers working with the Drupal Kit. ITS uses the University’s Enterprise GitHub instance for development of the Kit software, and also for issue tracking/bug reports.

Tip

Code pull and push actions in the University’s Enterprise GitHub instance requires SSH protocol, rather than HTTPS. You will need to add an SSH key to https://github.austin.utexas.edu/settings/keys for any machine you plan on using for local development.

Developers using Pantheon are required to use Git to manage and deploy their site code. Developers using other hosting platforms are strongly encouraged to use a version control system to manage their site code.

Version control references

Hosting

The Drupal Kit has currently been confirmed to be compatible with the CMS Hosting Platform (Pantheon) service. To discuss compatibility with other hosting platforms, please email drupal-kit-support@utlists.utexas.edu.

Hosting references

Scaffolding

Scaffolding is a one-time process of creating the file structure for a functional codebase, including the creation of a composer.json file which provides directives on what dependencies are needed.

Starting in version 8.8, Drupal core provides scaffold templates for creating a Drupal project. However, Drupal Kit site developers should use the custom scaffold script maintained by ITS. Instructions for scaffolding a UTDK codebase are included in the Non-Pantheon setup and Pantheon setup documentation.

Scaffolding references

Build & deployment

Previous versions of Drupal allowed code to be imported directly to a server environment from Drupal.org using Secure File Transfer Protocol (SFTP). The Composer-managed nature of the current version of Drupal and the Drupal Kit now requires developers to think about managing their code and servers as two distinct steps: building the codebase, and deploying it to a server environment.

  • The build process involves generating a build artifact that has all the code necessary for the site to function.

  • The deployment process involves placing the build artifact in a target server environment and executing any necessary configuration commands.

These processes are related. They can occur either through manual execution of a series of build steps or through an automated continuous integration process.

Pantheon’s recommended method for deployment is called Integrated Composer. The Drupal Kit follows this methodology for integration with Pantheon. See Pantheon setup.

Non-Pantheon developers are responsible for developing their own build-and-deploy workflow. The use of Composer in production server environments is :ref:`not recommended <https://stackoverflow.com/questions/42065931/why-should-i-never-run-composer-update-in-production>`_. Developers should build their codebase outside of the production environment and capture the result of that build process as a build artifact that can be deployed to the production environment.

Build & deployment references

Installation

Installation is the final step of creating a Drupal Kit site, once the codebase has been scaffolded, built, and deployed to a server environment. This is the process of populating the site’s database with configuration defined by the selected installation profile (in the case of Drupal Kit, the utexas profile). Installation can be run in the browser via the Drupal admin UI, or at the command line via Drush.

With a properly scaffolded Drupal Kit codebase, installation should proceed as with any normal Drupal site; environment considerations such as database connection, web server, and hostname will vary. That said, a generic list of steps for installation follow:

  1. Establish a database connection in a settings.local.php file in web/sites/default.

  2. Initiate the site installation by either navigating to the domain associated with the site (e.g., https://example.edu). Or, if you use Drush:

drush site:install utexas --site-name="My Site"

Installation options

The site installation process includes some initial configuration options, including:

Demo content

When selected, the installation will generate the following content:

  • Header menu placed in the “Header Secondary” region.

  • A populated Main navigation menu with links and sub-links.

  • Site branding and social links placed in the “Left Footer” region.

  • Footer menu in the “Middle Footer” region.

  • Call to action in the “Right Footer” region.

If you use the Drush site-install command, an extra argument needs to be added in order to prevent the demo content from being generated:

drush site:install utexas utexas_installation_options.default_content=NULL -y

Installation references