INSTALLATION.md

Installation

Instructions on how to install and configure this Drupal project template for Pantheon, CircleCI, and local Docksal development.

---

Installer method

@kanopians - Please use the internal, private repository.

CLI installation method

Create a GitHub repository for the project.

Install GitHub CLI if you don't have it. brew install gh

Install the Repo Config GH CLI extension gh extension install twelvelabs/gh-repo-config

Create a GitHub team (Optional)

gh api /orgs/<organization>/teams --method POST -f org=<organization> -f name=<team_name> -f privacy=closed

• organization - The GitHub organization name.
• repo_name - The name of your new repository.
• team_name - The name of the team created.

Create and clone your new repository

cd ~/Projects (Or where ever you keep your sites.)

gh repo create <organization>/<repo_name> --template kanopi/drupal-starter --private --team <team_name> --clone

cd <repo_name>

NOTE: Use --public instead of --private for a public repository.

Configure GitHub Repository Configuration

Edit the three files in /.github/config/

• /branch-protection/main.json - Configures branch protection rules on the main branch. Branch Rules Reference
• repo.json - Configures the repositories' settings. Repository Update Reference
• topics.json - Configures the repositories' topics/tags.

Run gh repo-config apply to apply the configuration to GitHub.

---

Start Docksal

• Edit .docksal/docksal.env
  • Update hostingsite to the <repo_name> used above. This should also be your Pantheon <site_name> used below.
• Run fin start

---

Create the site in Pantheon

fin terminus site:create --org=<org_id> —-region=<region> -- <site_name> <label> <upstream_id>

• site_name - Machine name of the project
• label - Friendly project name
• upstream_id - Currently Drupal 10 Start State - 7f9fd7d4-77ec-4e6b-a73f-d32b93a1c6b1
• Run fin terminus upstream:list to see all.
• org_id - The UUID of your Pantheon organization.
• Run fin terminus org:list to see all.
• region Codes for which region to create the site.
• au - Australia
• ca - Canada
• eu - European Union
• us - United States

Kanopians: Link more complete Cacher.

Install Drupal using the minimal install profile

fin terminus drush <site_name>.dev -- site-install minimal -y --site-name=<drupal_site_name> --account-name=<account_name> --account-mail=<account_mail> --site-mail=<site_mail>

• drupal_site_name - Friendly name of the site.
• account_name - User 1's machine name.
• account_mail - User 1's email.
• site_mail - For Drupal system mailings.

Add Redis to the Pantheon site

fin terminus redis:enable <site_id>

See A note about Redis on Pantheon below.

Configure Docksal

@TODO See UI method below until this is documented.

Configure CircleCI

@TODO See UI method below until this is documented.

Site Build Drupal

@TODO See UI method below until this is documented.

---

UI Installation Method

Create a new Drupal project.

Create a minimal site install

Set the basic details for the site

Add Redis to the project

Configure Pantheon

• 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.

Create a GitHub repository for the project.

• 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

Configure Docksal

• 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.

CircleCI project setup

• 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

---

Drupal setup

We have removed all opinions about which modules should be installed in Drupal.

Instead, we have created the kanopi/saplings Drupal recipe to require, intsall, and configure the modules and content types we use on most Drupal builds. Please visit that repository to continue using that.

A note about Redis on Pantheon.

• We enabled Redis on Pantheon in an earlier step.
• Before it can be configured, the Drupal Redis module needs to be enabled and pushed to Pantheon. It is a two commit process.
• Once the module has been enabled and verified on Pantheon:
  • Uncomment the Redis config in /assets/pantheon_setting_defaults.inc.
  • 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.

Configuring Cron on CircleCI for use with Pantheon

Cron can be ran two different ways.

1. Accessing through the URL provided on the Status Report.
2. Using Drush through Terminus.

What can happen sometimes is that we don't configure cron to run which then makes it so we manually need to run it. Within the .circleci/config.yml there is now a workflow titled run_cron that will run a terminus command then drush then the core cron command.

Running the URL process on Pantheon can timeout and is sometimes not recommended for a Cron Process that takes longer than 60 seconds.

Running Drush through Terminus is the next possible way. With this there are no time-out restrictions. This is usually done by running the following command in the terminal.

terminus drush site-id.site-env -- core:cron

We have made it so that this can be automated and done through CircleCI.

To configure

• Go to the project in CircleCI.
• Click on Project Settings
• Click Triggers
• Click Add Trigger
• Select Schedule from the Trigger type
• Configure the Trigger
  • Trigger Name: (The name should be prefixed with the words "cron job", example "cron job test")
  • Trigger Description: (This is a description about what this trigger does)
  • Pipeline to run: (This can stay as is)
  • Repeats: Weekly
  • Repeats on these days: (Select all 7 days)
  • Repeats on these months: (Select all 12 months)
  • Start Time: (See Note 1)
  • Repeats Per Hour: (See Note 2)
  • Branch of Tag Name: (Set to whatever the name of the main branch is in the project)
  • Pipeline Parameters
    • Click Add Parameters
      • Name: cron_env
      • Type: string
      • Value: (Name of the environment on Pantheon to run cron on defaults to live)
      • Click Add Parameters
  • Attribution: Leave it as it is (Scheduling System)
  • Click Save Trigger

NOTE 1 Configuring the Start time will depend on the need of the project. This is what hour the cron should be ran. Usually in live it is recommended to run maybe once an hour so all the items would be checked. But in other environments maybe it only needs to be ran in the morning so only specific times would be selected. Gauge the need of the project.

NOTE 2 Configuring the Repeats Per Hour will also dependo n the need of the project. If you aren't doing something that relies heavily on cron running maybe it's only 1. There may be times where you need the cron to run every 15 minutes and so setting to 4 is necessary. There are also times where you rely heavily on cron and there for need it to run every 6 minutes so setting to 12 is required. 12 is the max number we can set this to which means that we can only run this every 6 minutes.

NOTE While this is only configured to run with Pantheon the same sort of concept can be adapted to run on any other type of job.

workflows:
  workflow_name:
    when:
      and:
        - equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
        - matches: { "pattern": "^(example prefix).*", "value": << pipeline.schedule.name >> }
    jobs:
      ...