From 8ff06de5bae84c636c24b2209eae002304ad1246 Mon Sep 17 00:00:00 2001 From: Simon Hobbs Date: Mon, 13 Nov 2023 22:19:20 +1100 Subject: [PATCH] Create README-PASS-ONBOARDING.md Proposed draft of technical onboarding for PAAS sites. --- README-PASS-ONBOARDING.md | 189 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 README-PASS-ONBOARDING.md diff --git a/README-PASS-ONBOARDING.md b/README-PASS-ONBOARDING.md new file mode 100644 index 0000000..f8128a1 --- /dev/null +++ b/README-PASS-ONBOARDING.md @@ -0,0 +1,189 @@ +# GovCMS PaaS On-boarding + +This document is applicable when you have been provisioned a GovCMS PaaS site. You should +read this before beginning your site build or migration, as there are choices you can make +now which will effect your project for many years. + +This document will break down these choices, explain the defaults, and help guide you to +decide what features you may want to change. + +This document is technical. If your site is being built by a vendor you should request +them to review this and offer an explanation for any choices made. + +## History of the current PaaS structure + +Initially PaaS sites had a custom "scaffold" that was an un-opinionated Drupal project +plus the GovCMS profile. Clients who needed to make simple alterations (SaaS plus a litte +sugar) didn't have any guide rails and might replace the whole setup with a +bespoke Drupal application that wasn't best practice. Additionally, the GovCMS support +teams had two maintain two scaffolds with a lot of duplicated settings. + +Some changes to were made in about 2020 to get the PaaS structure "more like SaaS" and +enable small additions without drastically altering the GovCMS building blocks. Some +features included: + + * Allow patches and extra modules without modifying the composer.json + * Allow custom commands without modifying the `.ahoy.yml` + * Allow enabling and disabling different types of tests without modifying `.gitlab-ci.yml` + * Allow customisation of $settings and other aspects in web/sites/default without modifying default files. + * Include Lagoon-friendly Drupal settings from separate package that worked equally well for SaaS and PaaS + +You can see that most of these changes enable custom functionality from the core SaaS +product, without butchering the core product. One of the goals was to enable future +"SaaS+" options, and provide a migration path from simple PaaS sites to move back to SaaS. +(Ship Shape or the Site Audit CI job can tell you how close your PaaS site is to SaaS.) + +## How much customisation is too much customisation? + +The biggest risk of customising your PaaS site is that both a) it no longer resembles a +'normal' SaaS site and b) it doesn't resemble a 'normal' Drupal site either. + +The less customisation the better! However, the goal here is to hint at the tipping point +where you would be better off making your site "more like generic Drupal". In this way +you can leverage the brains trust of the wider Drupal community, eg. the `#australia-nz` channel +in Drupal Slack. + +## Your README + +You should replace your README.md with custom content the describes your project and any +key links, practices and decisions. It is misleading to leave the default README as it is +- your project is a website, not a scaffold - but you can definitely link to the original +README in the scaffold so that the reader understands the history. + +## The custom/composer directory. + +The `custom/composer/composer.json` file was created so that edge cases could be solved +by GovCMS team without modifying a SaaS setup. It has no real benefit for PaaS projects. + +This also applies to `custom/composer/patches.json`. + +Side note: it's not a bad idea to specify a directory like `custom` where you put your +custom stuff. This helps other developers clearly understand what is vanilla and what is +custom. + +## Profile vs Packages + +You are on PaaS so the expectation is you'll need to add new Composer packages (ie Drupal +modules). Unfortunately since the GovCMS distribution "pins" packages for auditing and +control reasons, the more packages you add, the more you increase the chance that +Composer can't resolve the dependency tree. + +*What you can change* + +If you are building a very custom site, you should remove the "govcms/govcms" requirement +and simply require the packages you want. Don't pin your packages! Pinned packages are not +recommended by Composer so you should be doing things in a generic way. + +*Risks/benefits* + +If you add a lot of modules is you could get stuck unable to update with Composer. If this +happens with a security update you may need to find and apply patches. It can be gnarly +resolving these issues and you don't want to be managing a lot of patches and packages forks. + +But should you make this change? This is really up to the team supporting your site. The +main point to remember: "Requiring the GovCMS profile will make my site harder to support +the more that I customise it." + +## About the profile + +Everything the GovCMS profile does could be done in a module. The main exception is that +customising the installer is best done in the profile, but after the site is installed that +will never be used again. + +*What you can change* + +You can install Drupal without the GovCMS profile, that's something you'd want to do from +the outset. + +*Risks/benefits* + +If you read through the code of the profile, it's mostly about SaaS control. The downside +is the GovCMS installer setups up security very well. If you want to follow SaaS practices, +say for consistency across your sites, you need to set it up TFA/etc manually by emulating +the configuration. There is an issue about this here https://github.com/govCMS/GovCMS/issues/913 + +## Settings.php and friends + +All the Lagoon configuration is loaded from `vendor/govcms/govcms-scaffold`. This practice +is very common with other hosting platforms like Platform.sh or Pantheon. + +Read through the default `sites/default/settings.php` carefullky as it has some tips for +customisation your settings without messing too much with local Docker Compose and remote +Lagoon configuration. + +Between `settings.local.php` (not committed to the repository) and `project.settings.php` +there is no need to edit any of the default setup. + +## Understand your deployment processes + +When deploying your site there are processes and settings that are different depending on +which environment the deployment is occurring: local/development/production. Locally you +can replicate deployment with `ahoy govcms-deploy`. + +There are some settings in the `.env` file which will impact what happens when your site is +being deployed. You can read about these in the support documentation - they are all settings +you should consider with regards to your team's preferred workflow. + +*`GOVCMS_DEPLOY_WORKFLOW_CONFIG`* + +Controls whether to import config from `config/default`. Setting this to `import` is +common for teams to control all config. Note that any config in `config/dev` will be +imported during this process. + +Setting this to `retain` is used if settings are changed through the UI by site builders. + +*`GOVCMS_DEPLOY_WORKFLOW_CONTENT`* + +Controls whether to sync production database on deployment. This is off by default - you +wouldn't want to sync a large database on deployment to a dev environment! + +*`GOVCMS_DEPLOY_ENABLE_MODULES`* + +By default this is enabled and will force install various modules, but all these modules +can be installed through your config, so you are better to control any variations with +config_ignore or config_split. + +## Ahoy commands + +The `.ahoy.yml` is set up so you can put custom commands in the `custom/ahoy.yml`. If you +have started to move composer packages and patches into your composer.json and you're +not using `custom/` for anything, you might consider adding your custom commands straight +to the main `.ahoy.yml`, clearly labelled at the bottom.' + +## Gitlab CI configuration + +The `.gitlab-ci.yml` and `.gitlab-ci-inputs.yml` is very abstracted setup that is desiged +to allow various types of tests to be turned on and off. A custom .gitlab-ci.yml can be +faster and easier to understand and customise. + +For example, here's a fast CI setup that just checks for coding standards and shows a +deployment message, which is great for teams that are not writing behat/phpunit tests. + +``` +--- +image: gitlab-registry-production.govcms.amazee.io/govcms/govcms-ci${GOVCMS_CI_IMAGE_VERSION} + +stages: + - testing + - deploy + +lint: + before_script: + - composer install + stage: testing + script: + - ./vendor/bin/phpcs -s --standard=tests/phpcs.xml --extensions='php,module,theme' ./web/*/custom + allow_failure: true + +# Deploy summary. +notice: + variables: + GOVCMS_DASHBOARD: "https://dashboard.govcms.gov.au/projects" + script: + - echo "Deployment has been triggered on Lagoon. See $GOVCMS_DASHBOARD/$CI_PROJECT_NAME/$CI_PROJECT_NAME-$(echo $CI_COMMIT_REF_NAME | sed -e 's/[^[:alnum:]-]/-/g')/deployments" + stage: deploy +``` + + + +