Instructions on how to install and configure this Drupal project template for Pantheon, CircleCI, and local Docksal development.
@kanopians - Please use the internal, private repository.
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
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.
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.
Edit the three files in /.github/config/
/branch-protection/main.json
- Configures branch protection rules on themain
branch. Branch Rules Referencerepo.json
- Configures the repositories' settings. Repository Update Referencetopics.json
- Configures the repositories' topics/tags.
Run gh repo-config apply
to apply the configuration to GitHub.
- Edit
.docksal/docksal.env
- Update
hostingsite
to the<repo_name>
used above. This should also be your Pantheon<site_name>
used below.
- Update
- Run
fin start
fin terminus site:create --org=<org_id> —-region=<region> -- <site_name> <label> <upstream_id>
site_name
- Machine name of the projectlabel
- Friendly project nameupstream_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
- Australiaca
- Canadaeu
- European Unionus
- United States
Kanopians: Link more complete Cacher.
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.
fin terminus redis:enable <site_id>
See A note about Redis on Pantheon below.
@TODO See UI method below until this is documented.
@TODO See UI method below until this is documented.
@TODO See UI method below until this is documented.
- 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 todev
to start but when you release the project to production it should be changed tolive
* Runfin install-kdcl-basic
after you have set thetheme name that you want.
- Update
- 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.
- docksal.env
- 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.
- Update the
- 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
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.
- 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.
- Uncomment the Redis config in
Cron can be ran two different ways.
- Accessing through the URL provided on the Status Report.
- 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
- 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:
...