Wunder template for Drupal projects

This project template is an opinionated fork of the popular Drupal-composer template, configured to automatically deploy code to a Kubernetes cluster using CircleCI. Everything that works with the Drupal-composer project template will work with this repository, so we won't duplicate the documentation here.

Getting started

• Click "Use this template" to generate a new project,
  • select the correct owner,
  • name the project as client-COUNTRYCODE-CLIENT-PROJECT,
  • make the repository private (unless the project is public).
• Clone the new project locally and modify its details:
  • composer.json name,
  • silta/silta.yml values,
  • grumphp.yml tasks, including the project name in git_commit_message regex.
• Log in to CircleCI using your Github account and add the new project using existing config.
• Configure automatic autolinks for the project's JIRA environment.

For additional instructions, please see the Silta documentation.

Main environment

• URL: https://main.drupal-project.dev.wdr.io
• Drush alias: drush @main st
• SSH: ssh [email protected] -J [email protected]

Drush alias for the current Silta feature branch deployment is drush @current st.

Environment variables for silta_dev context

The following secret variables are defined in the file silta/silta.secret for the context silta_dev:

• TEST_KEY - secret key for testing purposes.

Local environment

• Appserver: https://drupal-project.lndo.site
• Adminer: http://adminer.drupal-project.lndo.site
• Elasticsearch: http://localhost:9200, http://elasticsearch.lndo.site
• Kibana: http://localhost:5601, http://kibana.lndo.site
• Mailhog: http://mail.lndo.site
• Varnish: https://varnish.drupal-project.lndo.site
• Drush alias: lando drush @local st
• SSH: lando ssh (-s <service>)

Setup

1. Install the latest Lando and read the documentation.
2. Update your project name and other Lando Drupal 10 recipe's parameters at .lando.yml.
3. Run lando start.

Services

• adminer - uses Adminer database management tool.
• chrome - uses selenium/standalone-chrome image, uncomment the service definition at .lando.yml to enable.
• elasticsearch - uses official Elasticsearch image, uncomment the service definition at .lando.yml to enable. Requires at least 4GiB of memory.
• kibana - uses official Kibana image, uncomment the service definition at .lando.yml to enable.
• mailhog - uses Lando MailHog service.
• node - uses Lando Node service.
• varnish - uses Lando Varnish service, uncomment the service definition at .lando.yml to enable.

Tools

• lando - tools / commands overview.
• lando grumphp <commands> - run GrumPHP code quality checks. Modified or new files are checked on git commit, see more at lando grumphp -h or wunderio/code-quality.
• lando npm <commands> - run npm commands.
• lando phpunit <commands> - run PHPUnit commands.
• lando varnishadm <commands> - run varnishadm commands.
• lando xdebug <mode> - load Xdebug in the selected mode(s).

Development advices

Drupal core tips

• Updating Drupal core.
• Altering scaffold files (robots.txt, .htaccess etc.).

Varnish and Purge configuration

• Enable Varnish by uncommenting Lando Varnish configuration in .lando.yml: (services → varnish and proxy → varnish) and run lando rebuild -y.
• Purge and Varnish Purge settings configuration is set in the basic installation profile that can be installed via lando drush si basic -y. This configuration should work out of the box.
• For sites that have already been installed:
  • Install Purge and related modules: lando drush en purge purge_drush purge_processor_lateruntime purge_queuer_coretags purge_tokens purge_ui varnish_purger varnish_purge_tags -y.
  • Make sure that a value is set for Browser and proxy cache maximum age at admin/config/development/performance to make Varnish act on pages.
  • Navigate to Purge administration page (/admin/config/development/performance/purge), click "Add purger" → "Varnish Purger" and configure it:
    • Name: "Varnish Purger"
    • Headers: Cache-Tags: [invalidation:expression]
    • Save
  • Export the created configuration: lando drush cex -y.
  • Note the ID on the created varnish_purger.settings.<PURGER_ID>.yml file.
  • Open web/sites/default/settings.php, find all the varnish_purger.settings.f94540554c values and replace the ID with the one from the newly exported configuration.
  • Run lando drush cr.
  • Varnish should now be available in its own host and purged when content is updated.

Note: Default Purge setup is using purge_processor_lateruntime module that'll empty the queue on page requests. This should work well enough for most sites that need immediate clearing of purge queues when content is being saved.

Running tests

The PHPUnit test framework is predefined in this project, see phpunit.xml for details. Also, there is a minified web/modules/custom/phpunit_example module included from examples module for learning purposes.

Testing examples

Use lando phpunit to run the PHPUnit commands.

• run one test class: lando phpunit path/to/your/class/file.php,
• list groups: lando phpunit --list-groups,
• run all the tests in a particular group: lando phpunit --group Groupname.

Secrets handling

Silta CLI is a command-line tool that helps you manage secrets and configurations for your Silta projects. You can use Silta CLI to encrypt and decrypt files with the following commands:

• silta secrets encrypt --file silta/silta.secret --secret-key=$SECRET_KEY to encrypt a file.
• silta secrets decrypt --file silta/silta.secret --secret-key=$SECRET_KEY to decrypt a file.
• silta secrets --help for help.

To use these commands, you need a secret key that is used to encrypt and decrypt the data. It can be specified with the --secret-key flag (defaults to the SECRET_KEY environment variable). It is strongly advised to use a custom key for each project to ensure security and avoid conflicts. See Silta's documentation on how to use a custom decryption key in a CircleCI configuration.

You should use the following naming convention for your custom keys: SEC_{PROJECT_NAME}_{CONTEXT} where CONTEXT refers to the environment you are working on, such as silta_dev (development context) or silta_finland (production context). For example, if you are working on the drupal-project project in the silta_dev environment, you should use the SEC_DRUPAL_PROJECT_SILTA_DEV key.

The silta/silta.secret file is a YAML file that contains the encrypted secrets for your project in the default silta-dev context. You can add more files for other contexts, such as silta/silta-prod.secret for the production context.

Contributing

This project is maintained by Wunder. We welcome contributions from the community.

Commit message validation and ticketing system integration

Our project uses both JIRA and GitHub Issues for tracking and managing tasks. We use Autolinked references to convert ticket IDs into links for easy navigation. To ensure traceability, commit messages must include a valid ticket ID from either system, except for merge commits. Additionally, provide a clear description of the change.

The format is as follows:

• JIRA: [PROJECTKEY-123]: Description
• GitHub: [GH-123]: Description

Validation rules are implemented via GrumPHP git_commit_message component. Please see grumphp.yml for details.

Following these guidelines ensures our project remains organized and changes are traceable. Thank you for adhering to these standards.

Git workflow

Our default Git workflow is detailed in the WunderFlow repository. Please refer to it for more information.

Deployments

Project deployment is managed by CircleCI. Deployment configurations can be found in the .circleci/config.yml file.

Feature branches require manual approval for deployment by default to reduce CI costs. Other branches are deployed automatically but can be switched to manual approval if needed.

Manual approvals are handled through the approve-deployment job. A project maintainer can approve the deployment in the CircleCI UI by clicking the "approve-deployment" job label when marked as "Needs Approval."