This is the Drupal Composer Project with docksal configuration to easily get a site started.

Features:

• Drupal 9 - Composer Install
• Docksal Configuration
• Basic CircleCI configuration
• Project Readme

Please make this README as project specific as possible. Delete the things that are not relevant or add new sections as needed.

This repo is Pantheon specific at the moment

• Create a new drupal 8 project. This is because the Drupal 9 integrated composer flow is a little janky.

• Create a minimal site install

• Set the basic details for the site

• Add Redis to the project

• Go to the Pantheon dashboard for your project.

• Click on the Team tab.

• Click on Add organization

• Search for Kanopi Studios (Important: enter the full term (Kanopi Studios) to find this - if you just enter Kanopi, you will end up with the wrong group and things will not work).

• Select and add Kanopi Studios.

• Go to https://github.com/kanopi/drupal-starter

• Click on "Use this template" button.

• Make the owner Kanopi and the repo private, then click "Create repository from template"

• In the new repo, click on Settings and then the Manage Access tab.

• Click on "Invite teams or people" button.

• Search for and add Kanopi Studios and grant them Read access.

• Click on "Add kanopicode to this repository"

• Still in Settings, click on the Branches tab.

• Click on Add Rule.

• Make Branch name pattern match your default branch (e.g., main).

• Select "Require pull request reviews before merging"

• Click Create button

• Clone the new repo to your local.

• Create a development branch.

• Make the project specific changes listed below.

• Docksal

  • docksal.env
    • Update hostingsite to the machine name of the project in Pantheon
    • Update THEME to the name of the theme folder
    • hostingenv is set to dev to start but when you release the project to production it should be changed to live
    • Run fin install-kdcl-basic after you have set the theme name that you want.
  • settings.php
    • .docksal/etc/conf/settings.php is used for the local settings file for drupal.
  • vhost-overrides.conf
    • .docksal/etc/nginx/vhost-overrides.conf
    • Update the proxy url to use the pantheon machine name for the site you just created.
  • .pa11yci.js
    • Update the urls you would like to test in the array
    • Update README's pally section with the links to the correct urls.

• CircleCI

  • config.yml
    • Update the TERMINUS_SITE variable in line 2 to your Pantheon machine name for the project.
    • Update the THEME_NAME variable in line 3 to the folder name for your custom theme.
    • Update paths in JSON lock files in theme
    • If you would like Slack notifications when builds complete uncomment the slack portion. You will need to create a new CircleCI slack integration for the channel you want to post updates too & update the webhook URL.

• Run fin init to validate your local site.

• Run fin drush cex -y

• On a development branch, git add, commit and push all local changes.

• Create a PR in github.

• Circleci won't run this time because we haven't set it up yet. We need to commit the project-specific circleci config.yml first so we can setup circleci later.

• Merge PR (now we have our project-specific circleci config on the main branch so we can reference it from circleci). Circleci job will still not happen.

• Go to circleci

• Find your new project repo and click the "Set Up Project" button.

• Select the branch name option and select the main branch, and click on the "Lets go" button.

• Click on the gear for the project and click on the Advanced Settings tab.

• Enable "Only build pull request" and "Auto Cancel Builds" options. Update settings

• Enable the following modules: fin drush en components emulsify_twig admin_toolbar twig_tweak redis pantheon_advanced_page_cache -y; fin drush then gin -y; fin drush config:set system.theme admin gin -y; fin drush rcrt 'adminstrator' 'Adminstrator' -y;
• Set config export path in settings.php to $settings['config_sync_directory'] = '../config/';
• Export config.
• On a development branch, git add, commit and push all local changes.
• Submit a PR on github.
• Validate circleci job and multidev.
• Merge PR.
• Validate circleci job and Dev site.
• In your local, checkout and pull main branch.
• Creat new development branch.
• Uncomment the redis config in web/sites/default/settings.php.
• Git add, commit and push the change.
• Submit a PR in the github repo.
• Validate circleci job and deployment to multidev.
• Merge the PR.
• Validate circleci job deployment and Pantheon Dev site.

Please put links to the important places here. Imagine you know nothing about the project.

• Pantheon Dashboard
• CircleCI
• Teamwork
• Github Team

This is a one time setup.

Follow Docksal install instructions

1. Clone this repo into your Projects directory.
2. Change directory to the cloned folder.
3. Make your own version of the docksal-local.env file from the example and add your SECRET_TERMINUS_TOKEN to the file.
   • You don't need to do this if you set your token globally in Docksal
4. Initialize the site with fin init
5. Once the site has been initialized you'll get a url to go to in your browser to start dev'ing.

Modules are installed using composer. The process for installing a module would be the following:

fin composer require [package]

The standard composer command is used but with the Docksal specific command fin prepended to the beginning.

The theme is based off the Kanopi Design Component Library which uses Storybook and is originally forked from Emulsify DS.

The theme included is located within docroot/sites/themes/custom/THEME.

The Storybook Design System published to the gh-pages branch and is available at https://kanopi.github.io/REPO_NAME/

Locally, running fin npm run storybook or fin npm run build will build the Storybook at http:https://storybook.${VIRTUAL_HOST}

The theme uses Webpack and NPM to manage packages and run scripts.

• @TODO Hot Reloading in Drupal

• Theme development run fin npm run develop. This will watch for twig, js, and sass changes within the components directory.
• The development storybook URL http:https://storybook.${VIRTUAL_HOST}

For webpack storybook to work within a docksal container we needed to set watchOptions in docroot/themes/custom/THEME/.storybook/webpack.config.js

config.watchOptions = {
  aggregateTimeout: 200,
  poll: 1000,
}

The following commands are available with Node and should be prefixed with the command fin npm run.

The following commands are available with Docksal and should be prefixed with the command fin

The following commands are available with Composer and should be prefixed with the command fin composer

We have a Docksal command that will run pa11y-ci audits fin pa11y. When the command finishes the reports are available at the following url pa11y.$VIRTUAL_HOST

If you want to change the configuration of the Pa11y tests you can edit the .pa11yci.js file.

Note: This was cribbed from Phase2

• Navigate and open assets/custom-robots.txt
• Add appended robots.txt to file
• Run fin composer install

• Open composer.json
• Change the following:

    "[web-root]/robots.txt": {
      "append": "assets/custom-robots.txt"
    },
  

• To:

  "[web-root]/robots.txt": "assets/custom-robots.txt",
  

• Run fin composer install

Are there any projects specific quirks or setup that should be noted.

Deployments to the dev Pantheon environment is managed through Circle CI.

Pull requests will build a MultiDev environment and update the PR with a comment. We also have Lighthouse testing and other audits enabled.

Merges to main will merge Github to the Pantheon dev environment. During development our databases are Test and Dev. Once we have a launched product these will change to Live, Test and Dev.

1. Go to the project dashboard on Pantheon.
2. Backup databases for Test and Dev.
   1. To accomplish this you can go to the backups tab and backup everything or go to Database/Files and under Export 'export the database'.
3. Go to the environment you want to deploy to and make note of the tickets that are ready to deploy, document these in the deploy log message.
4. Once content has been deployed clone the Test database down to Dev.
5. Pull the database locally, make sure there are no config changes that need to be committed to code. If there are changes, commit those and deploy.
6. Tell the appropriate Slack channel that a deployment has taken place and include which tickets were deployed.