This project is a tailored fork of the popular drupal-composer template. It is designed for deploying to Kubernetes clusters via CircleCI.
-
Create a new project repository Click "Use this template" to generate a new project:
- Select the correct owner.
- Name the project as
client-COUNTRYCODE-CLIENT-PROJECT. - Set the repository to private (unless the project is public).
-
Clone and customize the repository Clone the new project locally and update its details:
- Update
README.mdwith the project details - Update
composer.jsonwith the project name - In real client projects, remove
/composer.lockfrom.gitignoreso the lockfile is committed and reproducible - Modify the
silta/silta*files values - Adjust
grumphp.ymltasks, including updating the project name in thegit_commit_messageregex - Configure local development environment:
- For DDEV: Update project settings in
.ddev/config.yaml - For rig: Set a unique
project_idin.rig/project.yaml, for example the repository name. rig keys its state and policy by this ID, so a generated project must not keep the template'sdrupal-projectID
- For DDEV: Update project settings in
- For AI-assisted development, follow the rig workflow to initialize rig with a unique project ID.
- For database synchronization, see ddev-wunderio-drupal
- Adjust
web/sites/default/settings.phpsettings (stage_file_proxyetc) - Adjust
config_splitsettings for silta (default), production, main, local environments
- Update
-
Set up CircleCI
- Log in to CircleCI using your GitHub account.
- Add the new project to CircleCI using the existing configuration.
-
Configure encryption keys and secrets
- Define encryption keys for
silta_devandsilta_finlandcontexts in the CircleCI project settings and backup the keys in LastPass. Use the following naming convention:SEC_{PROJECT_NAME}_{CONTEXT}whereCONTEXTis the environment, such assilta_devorsilta_finland. - Update the
.circleci/config.ymlfile with the correspondingsecret_key_envvalues. - Define the secret environment variables in the
silta/silta*.secretsYAML files for thesilta_devandsilta_finlandcontexts. - Encrypt the
silta/silta*.secretsfiles using the encryption keys and commit the encrypted files to the repository. - See the relevant Silta's documentation for details.
- Define encryption keys for
-
Enable JIRA integration
- Configure automatic autolinks for the project's JIRA environment to link ticket IDs to JIRA issues seamlessly.
For additional instructions, please refer to the Silta documentation.
- URL: https://production.drupal-project.finland.wdr.io
- Drush alias:
drush @production st - SSH:
ssh www-admin@production-shell.drupal-project -J www-admin@ssh.finland.wdr.io
The following secret variables are defined in the silta/silta-prod.secrets file for the silta_finland context:
TEST_KEY_PROD- Secret key for testing purposes.
- URL: https://main.drupal-project.dev.wdr.io
- Drush alias:
drush @main st - SSH:
ssh www-admin@main-shell.drupal-project -J www-admin@ssh.dev.wdr.io
The Drush alias for the current Silta feature branch deployment is drush @current st.
The following secret variables are defined in the silta/silta.secrets file for the silta_dev context:
TEST_KEY- Secret key for testing purposes.
This project uses DDEV for local development.
DDEV provides a containerized development environment with all necessary services preconfigured.
- Install DDEV
- Ensure Docker is running on your system
- Start the environment and set up your project:
# Start the DDEV environment
ddev start
# Authenticate SSH for database syncing
ddev auth ssh
# Synchronize local database with a remote environment
# Synchronization is provided by [ddev-wunderio-drupal](https://github.com/wunderio/ddev-wunderio-drupal)
# drush deploy and drush uli are part of ddev syncdb command.
ddev syncdbNote: All commands in the DDEV section should be run within the DDEV environment using ddev prefix (e.g., ddev drush uli), or by using ddev ssh to access the container shell first.
The project can be accessed at https://drupal-project.ddev.site
For a complete list of all available services, URLs, and ports, use:
ddev describeddev- Display available commandsddev adminer- Launch Adminer database management interfaceddev copilot [args]- Run GitHub Copilot CLI inside the rig agents container (see AI Workflow)ddev claude [args]- Run Claude Code inside the rig agents container (see AI Workflow)ddev grumphp <commands>- Run code quality checks (command provided by ddev-wunderio-drupal)ddev mailpit- Open Mailpit email testing interfaceddev npm <commands>- Execute npm commandsddev phpunit <commands>- Run test suites (command provided by ddev-wunderio-drupal)ddev varnishadm <commands>- Manage Varnish cacheddev xdebug <mode>- Configure Xdebug debugging modesddev syncdb [environment]- Sync database from remote environment (requires VPN andddev auth ssh(command provided by ddev-wunderio-drupal)
DDEV Elasticsearch configuration
This project includes Elasticsearch service for robust full-text search capabilities. It's automatically set up during DDEV initialization.
- Pre-configured with
analysis-icufor Unicode/multilingual text processing - Additional plugins can be defined in
.ddev/docker-compose.elasticsearch8.yaml
services:
elasticsearch:
environment:
- ELASTICSEARCH_PLUGINS=analysis-icu # Space-separated plugin list# Check Elasticsearch status
ddev exec -s elasticsearch "curl -s localhost:9200"
# List installed plugins
ddev exec -s elasticsearch "bin/elasticsearch-plugin list"Elasticvue is included for visualization and management at http://drupal-project.ddev.site:9005
DDEV WunderIO Drupal
The Drupal template includes the Wunder-specific ddev-wunderio-drupal addon. This addon provides additional functionality and tools specifically designed for Drupal development, including custom commands, configurations, and automation scripts to enhance your workflow.
For more information about the addon, configuration options, and available custom commands, see: https://github.com/wunderio/ddev-wunderio-drupal/tree/main
This addon is installed automatically when you run ddev start.
The automation is configured in .ddev/config.wunderio.yaml using a pre-start host hook:
hooks:
pre-start:
- exec-host: 'if [ ! -f "${DDEV_GLOBAL_DIR}/wunderio/core/wdr-core.sh" ]; then ddev add-on get wunderio/ddev-wunderio-drupal; fi'This means developers only need to clone the project and run ddev start; no manual addon installation step is required.
Common commands provided by the addon include:
ddev grumphpddev phpunitddev syncdb
Code quality tools
This project includes several tools to maintain code quality and consistency across the codebase.
Markdown files can be checked and automatically fixed using the following npm scripts:
# Check markdown files for linting issues
ddev npm run lint:md
# Automatically fix markdown linting issues where possible
ddev npm run lint:md:fixMarkdown linting rules are configured in .markdownlint.json at the project root.
The project also includes linting for JavaScript and CSS files:
# Check JavaScript files
ddev npm run lint:js
# Check CSS/SCSS files
ddev npm run lint:css
# Run all linting (JS, CSS, and Markdown)
ddev npm run lintAI Workflow (rig + Claude Code)
AI-assisted development runs through rig, which starts Claude Code in an isolated agents container next to the DDEV project. Drush, Composer, PHPUnit, GrumPHP, npm and log reads are provided as wdrmcp MCP tools that execute in the project's web container.
-
Install rig on the host (see the rig repository for instructions).
-
Start the project:
rig up
-
Start Claude Code or GitHub Copilot in the agents container:
ddev claude ddev copilot
- Project settings:
.rig/project.yaml(project ID, enabled packs, Drupal docroot, Node paths). Theproject_idmust be unique per project; see Getting started. This file can only narrow the central rig policy; commit changes to it. - Agent policy, MCP tools and Claude Code settings are managed centrally by rig and regenerated by
rig up; they are not stored in this repository.
- The agents container has no Docker socket access and no sudo.
- The project is mounted read-write, while
.rigand.ddevare mounted read-only inside the agents container. - Secrets (
.envfiles, keys, credentials, local settings) are kept out of the agent's reach. - The agent can commit but never pushes; pushing is done from the host.
Drupal core updates
- Updating Drupal core.
- Altering scaffold files (e.g.,
robots.txt,.htaccess).
Varnish and Purge configuration
This section describes how to set up Varnish caching and Purge functionality in your local development environment.
Note: Drush commands in this section should be run with the appropriate environment prefix (ddev).
The project includes ready-to-use Varnish configuration:
-
Configuration Import (Recommended)
-
For existing projects, simply import the configuration from
config/sync:drush cim -y
-
This applies all Purge and Varnish settings, including processors and purgers
-
-
Manual Configuration (for new sites)
- If config/sync is not available, follow these steps:
a. Install required modules:
drush en purge purge_drush purge_processor_lateruntime purge_queuer_coretags purge_tokens purge_ui varnish_purger varnish_purge_tags -y
b. Configure Varnish Purger:
- Set a value for Browser and proxy cache maximum age in
admin/config/development/performance - Navigate to
/admin/config/development/performance/purge - Click Add purger and select Varnish Purger:
- Name: "Varnish Purger"
- Type: "Tags"
- Request method: "BAN" (important: use BAN instead of PURGE for compatibility with Silta)
- Headers:
Cache-Tags:[invalidation:expression] - Save the configuration
c. Configure processors:
- Go to
/admin/config/development/performance/purge/processors - Ensure these processors are enabled:
drush_purge_invalidate(for manual invalidation via Drush)lateruntime(for batching invalidations)purge_ui_block_processor(for admin UI functionality)
d. Export the configuration:
drush cex -y
e. Update settings.php:
-
Find the purger ID in
varnish_purger.settings.<PURGER_ID>.yml -
Update
web/sites/default/settings.phpwith the correct purger ID:if (getenv('VARNISH_ADMIN_HOST')) { $config['varnish_purger.settings.<PURGER_ID>']['hostname'] = trim(getenv('VARNISH_ADMIN_HOST')); $config['varnish_purger.settings.<PURGER_ID>']['port'] = getenv('VARNISH_ADMIN_PORT') ? trim(getenv('VARNISH_ADMIN_PORT')) : '80'; }
-
Varnish Configuration: DDEV comes pre-configured with Varnish in
.ddevfolder. -
Testing Configuration:
ddev drush cr ddev exec curl -X BAN -H "Cache-Tags: config:system.performance" http://varnish
If working correctly, you should receive a "200 Ban added" response
-
Viewing Varnish logs:
ddev exec -s varnish varnishlog -i BAN -i Cache
-
BAN vs PURGE Method: Always use the "BAN" method in the Varnish purger configuration instead of "PURGE". The Silta Varnish configuration is set up to handle BAN requests but may reject PURGE requests with "405 Method Not Allowed" errors.
-
Processors: The default Purge setup uses the
purge_processor_lateruntimemodule, which empties the purge queue during page requests. This works well for most sites needing immediate cache clearing. Ensure all required processors are enabled. -
Cache Tags: The Varnish configuration is set up to handle cache tag invalidation with the
Cache-Tagsheader.
Testing
The PHPUnit test framework is predefined in this project. See phpunit.xml for details. A minified web/modules/custom/phpunit_example module from the examples module is included for learning purposes.
Note: Run these commands with the appropriate environment prefix (ddev phpunit).
- Run one test class:
phpunit path/to/your/class/file.php - List groups:
phpunit --list-groups - Run all tests in a particular group:
phpunit --group Groupname
Playwright is used for end-to-end browser testing. Tests are located in the tests/ directory and configured via playwright.config.ts.
Install Node dependencies if you haven't already:
ddev npm installPlaywright browsers are automatically installed inside the DDEV container on ddev start.
The TEST_BASE_URL environment variable is preconfigured in DDEV (see .ddev/config.yaml).
To run all tests:
ddev npx playwright testTests are split into Playwright projects named <type>-<browser>, shown in brackets in the test output (for example [e2e-firefox]):
e2e-chromium,e2e-firefox,e2e-webkit— functional end-to-end tests in each browser (everything not tagged@a11y)a11y-chromium— accessibility scans (tests tagged@a11y), Chromium only
Run one project with --project, for example ddev npx playwright test --project=e2e-firefox, or all projects of one type with a wildcard: ddev npx playwright test --project="e2e-*".
The GitHub Actions workflow runs e2e-* and a11y-* as separate jobs ("e2e" and "accessibility"), each with its own status check and report artifact.
Each run writes an HTML report to playwright/report/ (git-ignored, like everything under playwright/). To view it, start the report server inside the web container:
ddev playwright-reportIt prints the report URL for this project (https://novarnish.<project>.ddev.site:9323). Leave the command running while you browse the report; stop it with Ctrl+C.
- The URL uses the
novarnish.hostname. The Varnish add-on serves the main<project>.ddev.sitehostname and moves the web container tonovarnish.<project>.ddev.site, and DDEV only exposes the web container's extra ports on that hostname.https://<project>.ddev.site:9323returns a 404. Without Varnish, the command prints the main hostname instead. - Running
ddev npx playwright show-report playwright/report --host 0.0.0.0directly also works. The explicit report directory selects the configured output, and--host 0.0.0.0lets DDEV's router reach the server. Thehttp://0.0.0.0:9323address it prints is only valid inside the container. - Port 9323 is exposed through
web_extra_exposed_portsin.ddev/config.yaml. If the page doesn't load after you pull this change, runddev restartso DDEV applies the new port.
You can also open playwright/report/index.html directly in your browser without a server. The report itself works, but traces don't open from a file:// URL.
tests/accessibility.spec.ts uses axe-core (@axe-core/playwright) to scan pages against WCAG 2.0/2.1 A and AA rules.
Tests run as an anonymous visitor (front page, login form) and as admin (front page, "Add basic page" form). The a11y-chromium project loads the admin session from the setup step; the anonymous group clears it with test.use({ storageState: { cookies: [], origins: [] } }). Add new pages to the group that matches who sees them.
Before the scans, the suite creates an article promoted to the front page and deletes it afterwards (tests/helpers/content.ts), so the front page is scanned with content instead of the placeholder an empty site shows.
Any violations are attached as JSON to the test in the HTML report, and the test fails. Run only these tests with:
ddev npm run test:a11yThe script runs all a11y-* projects. Pass extra Playwright options after --, for example ddev npm run test:a11y -- --grep "login".
tests/helpers/drupal-test.ts— Custom Playwright test base providing adrupalhelper (via@drupal/playwright) for actions likedrupal.loginAsAdmin()tests/example.spec.ts— Example end-to-end test demonstrating basic page creationtests/accessibility.spec.ts— Automated axe accessibility scans
Silta CLI is a command-line tool to manage secrets and configurations for Silta projects. Use the following commands:
- Encrypt a file:
silta secrets encrypt --file silta/silta.secrets --secret-key=<secret_key_env> - Decrypt a file:
silta secrets decrypt --file silta/silta.secrets --secret-key=<secret_key_env> - Display help:
silta secrets --help
See the corresponding secret_key_env values in the .circleci/config.yml file for the silta_dev and silta_finland contexts. Refer to the Getting Started section for details.
This project is maintained by Wunder. Contributions from the community are welcome.
Commit message validation and ticketing system integration
Commit message validation is enforced by GrumPHP (git_commit_message) and requires a ticket ID in the subject. Use one of these formats:
TICKET-123: Capitalized subject
type(TICKET-123): Capitalized subject
Examples:
WNDR-446: Update composer dependencies
fix(WNDR-446): Add Drush 13 PRE_INITIALIZE hook
feat(GH-57): Add release automation command
Rules:
- Ticket format:
PROJECTKEY-123(for exampleWNDR-446,GH-57). - Subject must start with a capital letter after
:. - Allowed types in
type(...):feat,fix,chore,docs,style,refactor,perf,test,ci,build,revert. - Merge commits are excluded from this validation.
Type names follow the Conventional Commits specification.
Recommended (not required by the matcher):
- Keep body lines as bullet points explaining what and why.
- Add a
Refs:footer with key files.
Ticket IDs can be autolinked in GitHub using custom autolinks.
Refer to the WunderFlow repository for Git workflow details.
Deployments are managed with CircleCI. Configurations are in .circleci/config.yml.
- Feature branches require manual approval for deployment by default.
- Other branches deploy automatically but can be configured for manual approval.
Manual approvals are managed through the approve-deployment job in the CircleCI UI by clicking the "approve-deployment" job label when marked as "Needs Approval."