{"id":13579113,"url":"https://github.com/wunderio/drupal-project","last_synced_at":"2025-04-10T04:45:30.703Z","repository":{"id":31535937,"uuid":"129912689","full_name":"wunderio/drupal-project","owner":"wunderio","description":"Wunder's template for Drupal projects designed to work automatically with DDEV, Lando, CircleCI and Helm.","archived":false,"fork":false,"pushed_at":"2025-03-17T06:59:50.000Z","size":1660,"stargazers_count":35,"open_issues_count":30,"forks_count":6,"subscribers_count":30,"default_branch":"main","last_synced_at":"2025-03-17T07:35:04.515Z","etag":null,"topics":["circleci","ddev","drupal","helm","kubernetes","lando","silta","xdebug"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wunderio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-17T13:56:38.000Z","updated_at":"2025-03-13T16:27:35.000Z","dependencies_parsed_at":"2023-01-14T19:15:55.232Z","dependency_job_id":"aa1e8afe-0cb4-4dd3-9801-a395b314e8d0","html_url":"https://github.com/wunderio/drupal-project","commit_stats":null,"previous_names":[],"tags_count":7,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wunderio%2Fdrupal-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wunderio%2Fdrupal-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wunderio%2Fdrupal-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wunderio%2Fdrupal-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wunderio","download_url":"https://codeload.github.com/wunderio/drupal-project/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161237,"owners_count":21057552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circleci","ddev","drupal","helm","kubernetes","lando","silta","xdebug"],"created_at":"2024-08-01T15:01:36.664Z","updated_at":"2025-04-10T04:45:30.694Z","avatar_url":"https://github.com/wunderio.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Wunder template for Drupal projects\n\nThis project is a tailored fork of the popular [drupal-composer template](https://github.com/drupal-composer/drupal-project). It is designed for deploying to [Kubernetes](https://kubernetes.io/) clusters via [CircleCI](https://circleci.com/).\n\n## Getting started\n\n1. **Create a new project repository**\n  Click \"[Use this template](https://github.com/wunderio/drupal-project/generate)\" to generate a new project:\n   - Select the correct owner.\n   - Name the project as `client-COUNTRYCODE-CLIENT-PROJECT`.\n   - Set the repository to private (unless the project is public).\n\n2. **Clone and customize the repository**\n   Clone the new project locally and update its details:\n   - Update `README.md` with the project details\n   - Update `composer.json` with the project name\n   - Modify the `silta/silta*` files [values](https://github.com/wunderio/charts/blob/master/drupal/values.yaml)\n   - Adjust `grumphp.yml` tasks, including updating the project name in the `git_commit_message` regex\n   - Configure local development environment:\n     - For DDEV: Update project settings in `.ddev/config.yaml`\n     - For Lando: Update project settings in `.lando.yml`\n   - Update project name in `scripts/syncdb.sh` for database synchronization\n   - Adjust `web/sites/default/settings.php` settings (`stage_file_proxy` etc)\n   - Adjust `config_split` settings for silta (default), production, main, local environments\n\n3. **Set up CircleCI**\n   - Log in to [CircleCI](https://app.circleci.com/) using your GitHub account.\n   - Add the new project to CircleCI using the existing configuration.\n\n4. **Configure encryption keys and secrets**\n   - Define encryption keys for `silta_dev` and `silta_finland` contexts in the CircleCI project settings and backup the keys in LastPass. Use the following naming convention: `SEC_{PROJECT_NAME}_{CONTEXT}` where `CONTEXT` is the environment, such as `silta_dev` or `silta_finland`.\n   - Update the `.circleci/config.yml` file with the corresponding `secret_key_env` values.\n   - Define the secret environment variables in the `silta/silta*.secrets` YAML files for the `silta_dev` and `silta_finland` contexts.\n   - Encrypt the `silta/silta*.secrets` files using the encryption keys and commit the encrypted files to the repository.\n   - See the relevant [Silta's documentation](https://wunderio.github.io/silta/docs/encrypting-sensitive-configuration/#using-a-custom-encryption-key) for details.\n\n5. **Enable JIRA integration**\n   - Configure [automatic autolinks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#custom-autolinks-to-external-resources) for the project's JIRA environment to link ticket IDs to JIRA issues seamlessly.\n\nFor additional instructions, please refer to the [Silta documentation](https://github.com/wunderio/silta).\n\n## Production environment\n\n- **URL**: \u003chttps://production.drupal-project.finland.wdr.io\u003e\n- **Drush alias**: `drush @prod st`\n- **SSH**: `ssh www-admin@production-shell.drupal-project -J www-admin@ssh.finland.wdr.io`\n\n### Environment variables for `silta_finland` context\n\nThe following secret variables are defined in the `silta/silta-prod.secrets` file for the `silta_finland` context:\n\n- `TEST_KEY_PROD` - Secret key for testing purposes.\n\n## Main environment\n\n- **URL**: \u003chttps://main.drupal-project.dev.wdr.io\u003e\n- **Drush alias**: `drush @main st`\n- **SSH**: `ssh www-admin@main-shell.drupal-project -J www-admin@ssh.dev.wdr.io`\n\nThe Drush alias for the **current** Silta feature branch deployment is `drush @current st`.\n\n### Environment variables for `silta_dev` context\n\nThe following secret variables are defined in the `silta/silta.secrets` file for the `silta_dev` context:\n\n- `TEST_KEY` - Secret key for testing purposes.\n\n## Local development\n\nThis project supports two local development environments: DDEV (preferred) and Lando. Choose the one that best fits your workflow.\n\n### DDEV environment\n\n[DDEV](https://ddev.com/get-started/) provides a containerized development environment with all necessary services preconfigured.\n\n#### DDEV setup instructions\n\n1. Install [DDEV](https://ddev.com/get-started/)\n2. Ensure Docker is running on your system\n3. Start the environment and set up your project:\n\n  ```bash\n  # Start the DDEV environment\n  ddev start\n\n  # Authenticate SSH for database syncing\n  ddev auth ssh\n\n  # Synchronize local database with a remote environment\n  # See `scripts/syncdb.sh` for options\n  ddev syncdb\n\n  # Apply configuration changes\n  ddev drush deploy\n\n  # Get a one-time login link for admin access\n  ddev drush uli\n  ```\n\nNote: 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.\n\n#### DDEV services and access points\n\nThe project can be accessed at \u003chttps://drupal-project.ddev.site\u003e\n\nFor a complete list of all available services, URLs, and ports, use:\n\n  ```bash\n  ddev describe\n  ```\n\n#### DDEV common commands\n\n- `ddev` - Display available commands\n- `ddev adminer` - Launch Adminer database management interface\n- `ddev grumphp \u003ccommands\u003e` - Run code quality checks\n- `ddev mailpit` - Open Mailpit email testing interface\n- `ddev npm \u003ccommands\u003e` - Execute npm commands\n- `ddev phpunit \u003ccommands\u003e` - Run test suites\n- `ddev varnishadm \u003ccommands\u003e` - Manage Varnish cache\n- `ddev xdebug \u003cmode\u003e` - Configure Xdebug debugging modes\n- `ddev syncdb [environment]` - Sync database from remote environment (requires VPN and `ddev auth ssh`, see `scripts/syncdb.sh` for details)\n\n\u003cdetails\u003e\n\u003csummary\u003eDDEV Elasticsearch configuration\u003c/summary\u003e\n\n#### DDEV Elasticsearch configuration\n\nThis project includes Elasticsearch service for robust full-text search capabilities. It's automatically set up during DDEV initialization.\n\n##### Plugins configuration\n\n- Pre-configured with `analysis-icu` for Unicode/multilingual text processing\n- Additional plugins can be defined in `.ddev/docker-compose.elasticsearch8.yaml`\n\n```yaml\nservices:\n  elasticsearch:\n    environment:\n      - ELASTICSEARCH_PLUGINS=analysis-icu  # Space-separated plugin list\n```\n\n##### Useful commands\n\n```bash\n# Check Elasticsearch status\nddev exec -s elasticsearch \"curl -s localhost:9200\"\n\n# List installed plugins\nddev exec -s elasticsearch \"bin/elasticsearch-plugin list\"\n```\n\n##### Web interface\n\nElasticvue is included for visualization and management at \u003chttp://drupal-project.ddev.site:9005\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLando environment\u003c/summary\u003e\n\n### Lando environment\n\n[Lando](https://docs.lando.dev/) offers another containerized development option with a focus on simplicity and flexibility.\n\n#### Lando services and access points\n\n| Service | Description | Access |\n|---------|-------------|---------|\n| Web server | Primary web service | \u003chttps://drupal-project.lndo.site\u003e |\n| Adminer | Database management via [docker-adminer](https://github.com/dehy/docker-adminer) | \u003chttp://adminer.drupal-project.lndo.site\u003e |\n| Elasticsearch | Search functionality via Elasticsearch (uncomment in `.lando.yml` to enable) | \u003chttp://localhost:9200\u003e or \u003chttp://elasticsearch.lndo.site\u003e |\n| Kibana | Elasticsearch visualization (uncomment in `.lando.yml` to enable) | \u003chttp://localhost:5601\u003e or \u003chttp://kibana.lndo.site\u003e |\n| Mailpit | Email testing via [Mailpit](https://mailpit.axllent.org/) | \u003chttp://mail.lndo.site\u003e |\n| Varnish | Caching via Varnish | \u003chttps://varnish.drupal-project.lndo.site\u003e |\n| Drush | Drupal CLI tool | `lando drush @local st` |\n| SSH | Container shell access | `lando ssh (-s \u003cservice\u003e)` |\n| Node | JavaScript tooling | Included in web container |\n| Chrome | Browser testing via [selenium/standalone-chrome](https://hub.docker.com/r/selenium/standalone-chrome/) | Available in web container |\n\n#### Lando setup instructions\n\n1. Install [Lando](https://github.com/lando/lando/releases)\n2. Start the environment:\n\n  ```bash\n  lando start\n  ```\n\n#### Lando common commands\n\n- `lando` - Display available commands\n- `lando drupal \u003carguments\u003e` - Run Drupal core scripts\n- `lando grumphp \u003ccommands\u003e` - Run code quality checks\n- `lando npm \u003ccommands\u003e` - Execute npm commands\n- `lando phpunit \u003ccommands\u003e` - Run test suites\n- `lando varnishadm \u003ccommands\u003e` - Manage Varnish cache\n- `lando xdebug \u003cmode\u003e` - Configure Xdebug debugging modes\n- `lando syncdb [environment]` - Sync database from remote environment (requires VPN, see `scripts/syncdb.sh` for details)\n\n\u003c/details\u003e\n\n## Development tips\n\n\u003cdetails\u003e\n\u003csummary\u003eCode quality tools\u003c/summary\u003e\n\n### Code quality tools\n\nThis project includes several tools to maintain code quality and consistency across the codebase.\n\n#### Markdown Linting\n\nMarkdown files can be checked and automatically fixed using the following npm scripts:\n\n```bash\n# Check markdown files for linting issues\nddev npm run lint:md\n\n# Automatically fix markdown linting issues where possible\nddev npm run lint:md:fix\n```\n\nMarkdown linting rules are configured in `.markdownlint.json` at the project root.\n\n#### JavaScript and CSS Linting\n\nThe project also includes linting for JavaScript and CSS files:\n\n```bash\n# Check JavaScript files\nddev npm run lint:js\n\n# Check CSS/SCSS files\nddev npm run lint:css\n\n# Run all linting (JS, CSS, and Markdown)\nddev npm run lint\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCursor AI Code Editor\u003c/summary\u003e\n\n### Cursor AI Code Editor\n\nThis project uses [Cursor](https://docs.cursor.com/) as the recommended AI-powered IDE. Cursor enhances development productivity through AI-assisted coding features while maintaining compatibility with VSCode extensions and settings.\n\n#### Project-specific AI Rules\n\n- Rules are stored in `@.cursor/rules/` directory\n- Main configuration file: `@.cursor/rules/common.mdc`\n- Rules provide AI with project-specific context about:\n  - File organization and key project files\n  - Development environment setup\n  - Code standards and technology stack\n  - Git workflow and commit message formatting\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDrupal core updates\u003c/summary\u003e\n\n### Drupal core updates\n\n- [Updating Drupal core](https://www.drupal.org/docs/updating-drupal/updating-drupal-core-via-composer).\n- [Altering scaffold files](https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold#toc_4) (e.g., `robots.txt`, `.htaccess`).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eVarnish and Purge configuration\u003c/summary\u003e\n\n### Varnish and Purge configuration\n\nThis section describes how to set up Varnish caching and Purge functionality in your local development environment.\n\nNote: Drush commands in this section should be run with the appropriate environment prefix (`ddev` or `lando`).\n\n#### Configuration Overview\n\nThe project includes ready-to-use Varnish configuration:\n\n1. **Configuration Import (Recommended)**\n   - For existing projects, simply import the configuration from `config/sync`:\n\n      ```bash\n      drush cim -y\n      ```\n\n   - This applies all Purge and Varnish settings, including processors and purgers\n\n2. **Manual Configuration (for new sites)**\n   - If config/sync is not available, follow these steps:\n\n   a. **Install required modules**:\n\n      ```bash\n      drush en purge purge_drush purge_processor_lateruntime purge_queuer_coretags purge_tokens purge_ui varnish_purger varnish_purge_tags -y\n      ```\n\n   b. **Configure Varnish Purger**:\n      - Set a value for **Browser and proxy cache maximum age** in `admin/config/development/performance`\n      - Navigate to `/admin/config/development/performance/purge`\n      - Click **Add purger** and select **Varnish Purger**:\n        - **Name:** \"Varnish Purger\"\n        - **Type:** \"Tags\"\n        - **Request method:** \"BAN\" (important: use BAN instead of PURGE for compatibility with Silta)\n        - **Headers:** `Cache-Tags`: `[invalidation:expression]`\n        - Save the configuration\n\n   c. **Configure processors**:\n      - Go to `/admin/config/development/performance/purge/processors`\n      - Ensure these processors are enabled:\n        - `drush_purge_invalidate` (for manual invalidation via Drush)\n        - `lateruntime` (for batching invalidations)\n        - `purge_ui_block_processor` (for admin UI functionality)\n\n   d. **Export the configuration**:\n\n      ```bash\n      drush cex -y\n      ```\n\n   e. **Update settings.php**:\n      - Find the purger ID in `varnish_purger.settings.\u003cPURGER_ID\u003e.yml`\n      - Update `web/sites/default/settings.php` with the correct purger ID:\n\n        ```php\n        if (getenv('VARNISH_ADMIN_HOST')) {\n          $config['varnish_purger.settings.\u003cPURGER_ID\u003e']['hostname'] = trim(getenv('VARNISH_ADMIN_HOST'));\n          $config['varnish_purger.settings.\u003cPURGER_ID\u003e']['port'] = getenv('VARNISH_ADMIN_PORT') ? trim(getenv('VARNISH_ADMIN_PORT')) : '80';\n        }\n        ```\n\n#### Environment-Specific Setup\n\n##### DDEV (Recommended)\n\n1. **Varnish Configuration**: DDEV comes pre-configured with Varnish in `.ddev` folder.\n\n2. **Testing Configuration**:\n\n   ```bash\n   ddev drush cr\n   ddev exec curl -X BAN -H \"Cache-Tags: config:system.performance\" http://varnish\n   ```\n\n   If working correctly, you should receive a \"200 Ban added\" response\n\n3. **Viewing Varnish logs**:\n\n   ```bash\n   ddev exec -s varnish varnishlog -i BAN -i Cache\n   ```\n\n##### Lando\n\n1. **Enable Varnish**:\n   - Varnish configuration is already enabled in `.lando.yml` \u0026 `.lando/varnish.vcl`.\n\n2. **Testing Configuration**:\n\n   ```bash\n   lando drush cr\n   lando ssh -c \"curl -X BAN -H 'Cache-Tags: config:system.performance' http://varnish\"\n   ```\n\n### Important Notes\n\n- **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.\n\n- **Processors:** The default Purge setup uses the `purge_processor_lateruntime` module, which empties the purge queue during page requests. This works well for most sites needing immediate cache clearing. Ensure all required processors are enabled.\n\n- **Cache Tags:** The Varnish configuration is set up to handle cache tag invalidation with the `Cache-Tags` header.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRunning tests\u003c/summary\u003e\n\n### Running tests\n\nThe [PHPUnit](https://phpunit.de/) test framework is predefined in this project. See `phpunit.xml` for details. A minified `web/modules/custom/phpunit_example` module from the [examples module](https://www.drupal.org/project/examples) is included for learning purposes.\n\n#### Testing examples\n\nNote: Run these commands with the appropriate environment prefix (`ddev phpunit` or `lando phpunit`).\n\n- Run one test class: `phpunit path/to/your/class/file.php`\n- List groups: `phpunit --list-groups`\n- Run all tests in a particular group: `phpunit --group Groupname`\n\u003c/details\u003e\n\n### Secrets handling\n\n[Silta CLI](https://github.com/wunderio/silta-cli) is a command-line tool to manage secrets and configurations for Silta projects. Use the following commands:\n\n- Encrypt a file: `silta secrets encrypt --file silta/silta.secrets --secret-key=\u003csecret_key_env\u003e`\n- Decrypt a file: `silta secrets decrypt --file silta/silta.secrets --secret-key=\u003csecret_key_env\u003e`\n- Display help: `silta secrets --help`\n\nSee 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.\n\n## Contributing\n\nThis project is maintained by [Wunder](https://wunder.io/). Contributions from the community are welcome.\n\n\u003cdetails\u003e\n\u003csummary\u003eCommit message validation and ticketing system integration\u003c/summary\u003e\n\n### Commit message validation and ticketing system integration\n\nWe follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages, with an additional requirement for ticket IDs. Each commit message must include a valid ticket ID (except for merge commits) and follow the conventional commits format:\n\n```bash\n[PROJECTKEY-123]: (feat) Add new feature description\n\n- Detailed change description\n- Another relevant detail\n\nRefs: file1.ext, file2.ext\n```\n\nTypes include (used within parentheses):\n\n- feat: New feature (correlates with MINOR in semantic versioning)\n- fix: Bug fix (correlates with PATCH in semantic versioning)\n- docs: Documentation changes\n- style: Changes not affecting code meaning\n- refactor: Code changes neither fixing bugs nor adding features\n- perf: Performance improvements\n- test: Adding or correcting tests\n- build: Build system or dependency changes\n- ci: CI configuration changes\n- chore: Other changes not modifying src or test files\n\nBreaking changes must be indicated by appending a ! after the type/scope or including \"BREAKING CHANGE:\" in the footer.\n\nTicket ID formats:\n\n- JIRA: `[PROJECTKEY-123]: (type) Description`\n- GitHub: `GH-123: (type) Description`\n\nWe leverage [autolinked references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) to automatically convert ticket IDs into clickable links for easy navigation. This enhances traceability and accessibility across platforms.\n\nValidation rules are implemented via the GrumPHP `git_commit_message` component. See `grumphp.yml` for configuration details.\n\u003c/details\u003e\n\n### Git workflow\n\nRefer to the [WunderFlow repository](https://github.com/wunderio/WunderFlow) for Git workflow details.\n\n### Deployments\n\nDeployments are managed with CircleCI. Configurations are in `.circleci/config.yml`.\n\n- Feature branches require manual approval for deployment by default.\n- Other branches deploy automatically but can be configured for manual approval.\n\nManual approvals are managed through the `approve-deployment` job in the CircleCI UI by clicking the \"approve-deployment\" job label when marked as \"Needs Approval.\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwunderio%2Fdrupal-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwunderio%2Fdrupal-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwunderio%2Fdrupal-project/lists"}