Comment on page
Using in GovCMS SaaS
- Get access to GitLab project
- Check that support ticket to enable config imports was actioned
- Check that production has your user added with administrator role
- Check that you have all NPM 8 and NodeJS 16 available on your machine
- Read this whole page to make sure you understand the steps
- 1.Clone the GitLab project locally.
- 2.Create a new branch
- 3.# Login to GovCMS image repositorydocker login gitlab-registry-production.govcms.amazee.io -u <username>
- 4.ahoy up
- 6.ahoy refresh-db
- 7.Add the following file exclusions to
- 8.# Unblock admin user (user 1 or generate a new one).ahoy drush user:unblock [username]
You can lookup username by logging into production site or by running:
ahoy drush uinf $(drush sqlq "SELECT GROUP_CONCAT(name) FROM users_field_data")
Now, if you run
ahoy loginyou should be able to login to your local version of the site as an admin user.
- 1.# Pull latest production DB.ahoy refresh-db
ahoy drush cexand commit configuration changes.
- 4.Push to remote and wait for deployment to complete.
- 5.Upon successful deploy, create a new Merge Request against
masterbranch . This will get the active configuration into the main branch.
- 6.When merged, update your local branch against the latest
At this point, you should have a GovCMS project running in
masterenvironment in GovCMS SaaS with the default theme.
It is advised to perform all changes in a dedicated (feature) branch to test this part before applying any customisations.
Since GovCMS SaaS does not allow to install themes via Composer, CivicTheme source must be installed as a custom theme.
Using an automated script to discover required modules from theme dependencies (Drupal does not support this OOTB):
ahoy drush ev "require_once dirname(\Drupal::getContainer()->get('theme_handler')->rebuildThemeData()['civictheme']->getPathname()) . '/theme-settings.provision.inc'; civictheme_enable_modules();"
CivicTheme MUST be enabled before your custom theme is enabled
# Enable CivicTheme and set as default.
ahoy drush theme:enable -y civictheme
ahoy drush config-set -y system.theme default civictheme
ahoy drush config-set -y media.settings standalone_url true
# Enable admin theme and set as default (optional).
ahoy drush theme:enable -y adminimal_theme
ahoy drush config-set -y system.theme admin adminimal_theme
CivicTheme GovCMS helper module
civictheme_govcmsserves the purpose to remove unnecessary entities and configuration that ships with GovCMS.
Install it locally to automatically remove the configuration from DB to later have it exported without GovCMS entities.
- 1.Run in CLI container (
ahoy cli):cd web/modules/contrib# Download and extract the helper module.# Ensure to use the latest tag (not Release) https://github.com/salsadigitalauorg/civictheme_govcms/tagswget https://github.com/salsadigitalauorg/civictheme_govcms/archive/refs/tags/<latest-tag>.tar.gz && tar -xvf <latest-tag>.tar.gz && rm <latest-tag>.tar.gz# Enable module, run the command to remove entities and uninstall a module.drush pm-enable -y civictheme_govcmsdrush civictheme_govcms:remove-config --preserve=user_rolesdrush pm-uninstall -y civictheme_govcms# Delete the modulerm -Rf civictheme_govcms
- 2.Export updated configurationahoy drush cex -y
Consider naming your theme as close as possible to the name of the site. Do not include
civicthemeinto name to avoid confusions in code when maintaining a theme in the future.
Run in CLI container (
# Generate sub-theme.
# See php civictheme_create_subtheme.php --help
php civictheme_create_subtheme.php <SUBTHEME_MACHINE_NAME> "<SUBTHEME HUMAN NAME>" "<SUBTHEME HUMAN DESCRIPTION>" ../<SUBTHEME_MACHINE_NAME>
This should result in 2 directories:
# Enable sub-theme.
ahoy drush theme:enable <SUBTHEME_MACHINE_NAME> -y
# Set sub-theme as default.
ahoy drush config-set system.theme default <SUBTHEME_MACHINE_NAME> -y
- 1.Run on your host:cd themes/<SUBTHEME_MACHINE_NAME>nvm usenpm installnpm run build
- 2.Check that directory
- 3.Navigate to your site and assert that default styling was applied.
.gitignorefile in your new theme and remove the following linesstorybook-staticdistcomponents_combined.components-civictheme
- 2.Commit built assets.
CivicTheme comes with pre-set Block Content blocks configuration. Since Drupal does not support running install hooks in themes, a custom content provisioning script has to be used.
The provisioning needs to be run twice:
- 1.Locally - to capture created configuration for config entities (blocks, menus etc.)
- 2.In production - to populate the configuration with the default content. This step will be covered in the “Deployment” section below.
- 1.Login to the local instance of your site.
- 2.Navigate to
- 3.Press "Provision content" button.
- 4.Navigate to the homepage and observe that all blocks and menus are present.
- 5.Export config for created entities:ahoy drush cex -y
- 6.Commit and push to remote.
- 7.Wait for deployment to finish and login to the Drupal instance.
- 8.Navigate to
- 9.Press "Provision content" button.
- 10.Navigate to the homepage and observe that all blocks and menus are present.
- 1.Merge feature branch to
developand then to
- 2.Commit and push to remote.
- 3.Wait for deployment to finish and login to the Drupal instance.
- 4.Navigate to
- 5.Press "Provision content" button.
- 6.Navigate to the homepage and observe that all blocks and menus are present.
Only run this step once everything is working and looking as expected.
- 1.# Remove unnecessary files.rm themes/civictheme/civictheme_create_subtheme.phprm -Rf themes/civictheme/civictheme_starter_kit
- 2.Commit and push to remote.
- 1.Replace sub-theme logos in repository
themes/<SUBTHEME_MACHINE_NAME>/assets/logoswith site-specific versions.
- 3.Update sub-theme
screenshot.pngwith something more appropriate (optional).
npm run buildand commit changes.
Role Delegationmodule and allow
Site Administratorto delegate both GovCMS and CivicTheme roles. Ensure that CivicTheme roles have the same permissions with their GovCMS counterparts.
- 2.Login to the site and re-assign existing users from GovCMS roles to relevant CivicTheme roles.
- 3.Remove GovCMS admin roles and re-export configuration.