Skip to content

Latest commit

 

History

History
248 lines (162 loc) · 8.49 KB

INSTALLATION.md

File metadata and controls

248 lines (162 loc) · 8.49 KB
Raw

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 new Drupal project

Create a minimal site install

Create a minimal site install

Set the basic details for the site

Set the basic details for the site

Add Redis to the project

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.