diff --git a/.circleci/config.yml b/.circleci/config.yml index b41fe16f..1f58a580 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -57,10 +57,10 @@ workflows: - silta/drupal-deploy: &deploy name: deploy executor: silta - silta_config: silta/silta.yml,silta/silta.secret + silta_config: silta/silta.yml,silta/silta.secrets pre-release: - silta/decrypt-files: - files: silta/silta.secret + files: silta/silta.secrets # SEC_DRUPAL_PROJECT_SILTA_DEV holds the secret key for decryption purposes. # This is stored in CircleCI as an environment variable and also in LastPass. secret_key_env: SEC_DRUPAL_PROJECT_SILTA_DEV @@ -96,7 +96,7 @@ workflows: - silta/drupal-deploy: <<: *deploy name: deploy-main - silta_config: silta/silta.yml,silta/silta.secret,silta/silta-main.yml + silta_config: silta/silta.yml,silta/silta.secrets,silta/silta-main.yml requires: - build-main filters: @@ -122,7 +122,13 @@ workflows: - silta/drupal-deploy: <<: *deploy name: deploy-prod - silta_config: silta/silta.yml,silta/silta-prod.yml + silta_config: silta/silta.yml,silta/silta-prod.yml,silta/silta-prod.secrets + pre-release: + - silta/decrypt-files: + files: silta/silta-prod.secrets + # SEC_DRUPAL_PROJECT_SILTA_FINLAND holds the secret key for decryption purposes. + # This is stored in CircleCI as an environment variable and also in LastPass. + secret_key_env: SEC_DRUPAL_PROJECT_SILTA_FINLAND context: silta_finland requires: - build-prod diff --git a/README.md b/README.md index 0956308d..a3592600 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,200 @@ # Wunder template for Drupal projects -This project template is an opinionated fork of the popular [Drupal-composer template](https://github.com/drupal-composer/drupal-project), configured to automatically deploy code to a [Kubernetes](https://kubernetes.io/) cluster using [CircleCI](https://circleci.com/). Everything that works with the Drupal-composer project template will work with this repository, so we won't duplicate the documentation here. +This 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/). ## Getting started -- Click "[Use this template](https://github.com/wunderio/drupal-project/generate)" 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](https://github.com/wunderio/charts/blob/master/drupal/values.yaml), - - `grumphp.yml` tasks, including the project name in `git_commit_message` regex. -- Log in to [CircleCI](https://app.circleci.com/) using your Github account and add the new project using existing config. -- 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. +1. **Create a new project repository** + Click "[Use this template](https://github.com/wunderio/drupal-project/generate)" 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). -For additional instructions, please see the [Silta documentation](https://github.com/wunderio/silta). +2. **Clone and customize the repository** + Clone the new project locally and update its details: + - Update `README.md` with the project details. + - Update `composer.json` with the project name. + - Modify the `silta/silta*` files [values](https://github.com/wunderio/charts/blob/master/drupal/values.yaml). + - Adjust `grumphp.yml` tasks, including updating the project name in the `git_commit_message` regex. + - Adjust the `lando` configuration in `.lando.yml`. + +3. **Set up CircleCI** + - Log in to [CircleCI](https://app.circleci.com/) using your GitHub account. + - Add the new project to CircleCI using the existing configuration. + +4. **Configure encryption keys and secrets** + - 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`. + - Update the `.circleci/config.yml` file with the corresponding `secret_key_env` values. + - Define the secret environment variables in the `silta/silta*.secrets` YAML files for the `silta_dev` and `silta_finland` contexts. + - Encrypt the `silta/silta*.secrets` files using the encryption keys and commit the encrypted files to the repository. + - See the relevant [Silta's documentation](https://wunderio.github.io/silta/docs/encrypting-sensitive-configuration/#using-a-custom-encryption-key) for details. + +5. **Enable JIRA integration** + - 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. + +For additional instructions, please refer to the [Silta documentation](https://github.com/wunderio/silta). + +## Production environment + +- **URL**: +- **Drush alias**: `drush @prod st` +- **SSH**: `ssh www-admin@production-shell.drupal-project -J www-admin@ssh.finland.wdr.io` + +### Environment variables for `silta_finland` context + +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. ## Main environment -- URL: -- Drush alias: `drush @main st` -- SSH: `ssh www-admin@main-shell.drupal-project -J www-admin@ssh.dev.wdr.io` +- **URL**: +- **Drush alias**: `drush @main st` +- **SSH**: `ssh www-admin@main-shell.drupal-project -J www-admin@ssh.dev.wdr.io` -Drush alias for the **current** Silta feature branch deployment is `drush @current st`. +The Drush alias for the **current** Silta feature branch deployment is `drush @current st`. -### Environment variables for silta_dev context +### Environment variables for `silta_dev` context -The following secret variables are defined in the file `silta/silta.secret` for the context `silta_dev`: +The following secret variables are defined in the `silta/silta.secrets` file for the `silta_dev` context: -- `TEST_KEY` - secret key for testing purposes. +- `TEST_KEY` - Secret key for testing purposes. ## Local environment -- Appserver: -- Adminer: -- Elasticsearch: , -- Kibana: , -- Mailpit: -- Varnish: -- Drush alias: `lando drush @local st` -- SSH: `lando ssh (-s )` +- **Appserver**: +- **Adminer**: +- **Elasticsearch**: + - + - +- **Kibana**: + - + - +- **Mailpit**: +- **Varnish**: +- **Drush alias**: `lando drush @local st` +- **SSH**: `lando ssh (-s )` ### [Setup](https://docs.lando.dev/getting-started/installation.html) 1. Install the latest [Lando](https://github.com/lando/lando/releases) and read the [documentation](https://docs.lando.dev/). -2. Update your project name and other Lando [Drupal 10 recipe](https://docs.lando.dev/drupal/)'s parameters at `.lando.yml`. +2. Update your project name and other Lando [Drupal 10 recipe](https://docs.lando.dev/drupal/) parameters in `.lando.yml`. 3. Run `lando start`. ### [Services](https://docs.lando.dev/core/v3/services.html) -- `adminer` - uses [Adminer database management tool](https://github.com/dehy/docker-adminer). -- `chrome` - uses [selenium/standalone-chrome](https://hub.docker.com/r/selenium/standalone-chrome/) image, uncomment the service definition at `.lando.yml` to enable. -- `elasticsearch` - uses official [Elasticsearch image](https://hub.docker.com/r/elastic/elasticsearch), uncomment the service definition at `.lando.yml` to enable. Requires [at least 4GiB of memory](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html). -- `kibana` - uses official [Kibana image](https://hub.docker.com/r/elastic/kibana), uncomment the service definition at `.lando.yml` to enable. -- `mailpit` - uses custom [Mailpit service](https://mailpit.axllent.org/). -- `node` - uses Lando [Node service](https://docs.lando.dev/node/). -- `varnish` - uses Lando [Varnish service](https://docs.lando.dev/varnish/), uncomment the service definition at `.lando.yml` to enable. +- **Adminer**: Uses [Adminer database management tool](https://github.com/dehy/docker-adminer). +- **Chrome**: Uses the [selenium/standalone-chrome](https://hub.docker.com/r/selenium/standalone-chrome/) image. Uncomment the service definition in `.lando.yml` to enable. +- **Elasticsearch**: Uses the official [Elasticsearch image](https://hub.docker.com/r/elastic/elasticsearch). Uncomment the service definition in `.lando.yml` to enable. Requires [at least 4 GiB of memory](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html). +- **Kibana**: Uses the official [Kibana image](https://hub.docker.com/r/elastic/kibana). Uncomment the service definition in `.lando.yml` to enable. +- **Mailpit**: Uses the custom [Mailpit service](https://mailpit.axllent.org/). +- **Node**: Uses Lando's [Node service](https://docs.lando.dev/node/). +- **Varnish**: Uses Lando's [Varnish service](https://docs.lando.dev/varnish/). Uncomment the service definition in `.lando.yml` to enable. ### [Tools](https://docs.lando.dev/core/v3/tooling.html) -- `lando` - tools / commands overview. -- `lando drupal ` - run the Drupal core script with provided arguments. -- `lando grumphp ` - run [GrumPHP](https://github.com/phpro/grumphp) code quality checks. Modified or new files are checked on git commit, see more at `lando grumphp -h` or [wunderio/code-quality](https://github.com/wunderio/code-quality). -- `lando npm ` - run [npm](https://www.npmjs.com/) commands. -- `lando phpunit ` - run [PHPUnit](https://phpunit.de/) commands. -- `lando varnishadm ` - run [varnishadm](https://varnish-cache.org/docs/6.0/reference/varnishadm.html) commands. -- `lando xdebug ` - load [Xdebug](https://xdebug.org/) in the selected [mode(s)](https://xdebug.org/docs/all_settings#mode). +- **`lando`**: Lists available tools and commands. +- **`lando drupal `**: Run Drupal core scripts with arguments. +- **`lando grumphp `**: Run [GrumPHP](https://github.com/phpro/grumphp) code quality checks. +- **`lando npm `**: Run [npm](https://www.npmjs.com/) commands. +- **`lando phpunit `**: Run [PHPUnit](https://phpunit.de/) commands. +- **`lando varnishadm `**: Run [varnishadm](https://varnish-cache.org/docs/6.0/reference/varnishadm.html) commands. +- **`lando xdebug `**: Load [Xdebug](https://xdebug.org/) in the selected [mode(s)](https://xdebug.org/docs/all_settings#mode). -## Development advices +## Development tips -### Drupal core tips +### Drupal core updates - [Updating Drupal core](https://www.drupal.org/docs/updating-drupal/updating-drupal-core-via-composer). -- [Altering scaffold files](https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold#toc_4) (`robots.txt`, `.htaccess` etc.). +- [Altering scaffold files](https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold#toc_4) (e.g., `robots.txt`, `.htaccess`). ### Varnish and Purge configuration -- Enable [Varnish](https://varnish-cache.org) 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..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. +1. **Enable Varnish:** + - Uncomment the Varnish configuration in `.lando.yml` under `services → varnish` and `proxy → varnish`. + - Run `lando rebuild -y`. + +2. **Basic installation profile configuration:** + - Install the `basic` profile: `lando drush si basic -y`. + - This sets up Purge and Varnish Purge out of the box. + +3. **Configuration for installed sites:** + - Enable the required modules: + + ```bash + lando drush en purge purge_drush purge_processor_lateruntime purge_queuer_coretags purge_tokens purge_ui varnish_purger varnish_purge_tags -y + ``` + + - 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" + - **Headers:** `Cache-Tags`: `[invalidation:expression]` + - Save the configuration. + - Export the configuration: + + ```bash + lando drush cex -y + ``` + + - Find the purger ID in the exported `varnish_purger.settings..yml` file. + - Update `web/sites/default/settings.php`: + - Replace all occurrences of `varnish_purger.settings.` with the new purger ID. + - Clear the cache: + + ```bash + lando drush cr + ``` + + Varnish should now be configured to handle caching and purging when content is updated. + +**Note:** 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. ### Running tests -The [PHPUnit](https://phpunit.de/) 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](https://www.drupal.org/project/examples) for learning purposes. +The [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. #### Testing examples -Use `lando phpunit` to run the PHPUnit commands. +Use `lando phpunit` to run 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`. +- Run one test class: `lando phpunit path/to/your/class/file.php` +- List groups: `lando phpunit --list-groups` +- Run all tests in a particular group: `lando phpunit --group Groupname` ### Secrets handling -[Silta CLI](https://github.com/wunderio/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. +[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: -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](https://wunderio.github.io/silta/docs/encrypting-sensitive-configuration/#using-a-custom-encryption-key). +- Encrypt a file: `silta secrets encrypt --file silta/silta.secrets --secret-key=` +- Decrypt a file: `silta secrets decrypt --file silta/silta.secrets --secret-key=` +- Display help: `silta secrets --help` -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. +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. ## Contributing -This project is maintained by [Wunder](https://wunder.io/). We welcome contributions from the community. +This project is maintained by [Wunder](https://wunder.io/). Contributions from the community are welcome. ### Commit message validation and ticketing system integration -Our project uses both JIRA and GitHub Issues for tracking and managing tasks. We use [Autolinked references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) 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: +We use JIRA and GitHub issues for tracking tasks. Commit messages must include a valid ticket ID except for merge commits. Use the following format: - JIRA: `[PROJECTKEY-123]: Description` - GitHub: `[GH-123]: Description` -Validation rules are implemented via GrumPHP `git_commit_message` component. Please see `grumphp.yml` for details. +We 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. -Following these guidelines ensures our project remains organized and changes are traceable. Thank you for adhering to these standards. +Validation rules are implemented via the GrumPHP `git_commit_message` component. See `grumphp.yml` for configuration details. ### Git workflow -Our default Git workflow is detailed in the [WunderFlow repository](https://github.com/wunderio/WunderFlow). Please refer to it for more information. +Refer to the [WunderFlow repository](https://github.com/wunderio/WunderFlow) for Git workflow details. ### Deployments -Project deployment is managed by CircleCI. Deployment configurations can be found in the `.circleci/config.yml` file. +Deployments are managed with CircleCI. Configurations are in `.circleci/config.yml`. -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. +- Feature branches require manual approval for deployment by default. +- Other branches deploy automatically but can be configured for manual approval. -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." +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." diff --git a/drush/sites/self.site.yml b/drush/sites/self.site.yml index 257064af..7625e23c 100644 --- a/drush/sites/self.site.yml +++ b/drush/sites/self.site.yml @@ -20,11 +20,10 @@ main: root: /app/web uri: https://main.${PROJECT}.dev.wdr.io -#prod: -# host: production-shell.client-PROJECTNAME -# ssh: -# options: -J www-admin@ssh.finland.wdr.io -# user: www-admin -# root: /app/web -# uri: https://www.domain.com - +prod: + host: production-shell.${REPOSITORY} + ssh: + options: -J www-admin@ssh.finland.wdr.io + user: www-admin + root: /app/web + uri: https://production.${PROJECT}.finland.wdr.io diff --git a/silta/silta-prod.secrets b/silta/silta-prod.secrets new file mode 100644 index 00000000..17005bd9 --- /dev/null +++ b/silta/silta-prod.secrets @@ -0,0 +1 @@ +Salted__.`_ !%ѽgt?I5Wo0yx(2ߜ\}r \ No newline at end of file diff --git a/silta/silta.secret b/silta/silta.secret deleted file mode 100644 index 144e5b3a..00000000 Binary files a/silta/silta.secret and /dev/null differ diff --git a/silta/silta.secrets b/silta/silta.secrets new file mode 100644 index 00000000..a48e0865 --- /dev/null +++ b/silta/silta.secrets @@ -0,0 +1 @@ +Salted__ÈXokޝEuz81 Nb 'Q>(DJ TLwڊ \ No newline at end of file