This project contains only the canonical resources used to build a SiteFarm Drupal site for use on Pantheon.
- GitHub repo
- Free Pantheon sandbox site
- A CircleCI configuration to run tests and push from the source repo (GitHub) to Pantheon.
For more background information on this style of workflow, see the Pantheon documentation.
Before running the terminus build:project:create command, make sure you have all of the prerequisites:
- A Pantheon account
- Terminus, the Pantheon command line tool
- The Terminus Build Tools Plugin
- An account with GitHub and an authentication token capable of creating new repos.
- An account with CircleCI and an authentication token.
You may find it easier to export the GitHub and CircleCI tokens as variables on your command line where the Build Tools Plugin can detect them automatically:
export GITHUB_TOKEN=[REDACTED]
export CIRCLE_TOKEN=[REDACTED]
$ terminus build:project:create --stability=dev --team="University of California Davis" ucdavis/sitefarm-pantheon my-sitefarm-site
Replace "my-sitefarm-site" would your desired site machine name in Pantheon.
Once the build is completed, log into CircleCI and add the CircleCI Private SSH Key to your new project so that it can access the private repos on Bitbucket.
- On your new project's GitHub page, click on the
circleci|failedicon. - Now, on your new project's CircleCI project listing, click on the settings cog.
- Go to "SSH Permissions", then "Add SSH Key".
- Hostname:
bitbucket.org - Private Key: [copy/paste private key from Confluence]
Finally, click "rebuild" on the first failed CircleCI build to complete the install.
Now, you can clone down the GitHub repo and begin work.
Pantheon will serve the site from the /web subdirectory due to the configuration in pantheon.yml, facilitating a Composer based workflow. Having your website in this subdirectory also allows for tests, scripts, and other files related to your project to be stored in your repo without polluting your web document root.
One of the directories moved to the git root is /config. This directory holds Drupal's .yml configuration files. In more traditional repo structure these files would live at /sites/default/config/. Thanks to this line in settings.php, the config is moved entirely outside of the web root.
If you are just browsing this repository on GitHub, you may notice that the files of Drupal core itself are not included in this repo. That is because Drupal core and contrib modules are installed via Composer and ignored in the .gitignore file. Specific contrib modules are added to the project via composer.json and composer.lock keeps track of the exact version of each modules (or other dependency). Modules, and themes are placed in the correct directories thanks to the "installer-paths" section of composer.json. composer.json also includes instructions for drupal-scaffold which takes care of placing some individual files in the correct places like settings.pantheon.php.
So that CircleCI will have some test to run, this repository includes a configuration of Behat tests. You can add your own .feature files within /tests/features/.
When using this repository to manage your Drupal site, you will no longer use the Pantheon dashboard to update your Drupal version. Instead, you will manage your updates using Composer. Updates can be applied either directly on Pantheon, by using Terminus, or on your local machine.
Install Terminus 1 and the Terminus Composer plugin. Then, to update your site, ensure it is in SFTP mode, and then run:
terminus composer <sitename>.<dev> update
Other commands will work as well; for example, you may install new modules using terminus composer <sitename>.<dev> require drupal/pathauto.
You may also place your site in Git mode, clone it locally, and then run composer commands from there. Commit and push your files back up to Pantheon as usual.