selvbetjening.aarhuskommune.dk

Getting started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Installation

docker network create frontend
docker compose pull
docker compose up --detach

# Important: Use --no-interaction to make https://getcomposer.org/doc/06-config.md#discard-changes have effect.
docker compose exec phpfpm composer install --no-interaction

# Install the site
docker compose exec phpfpm vendor/bin/drush site:install os2forms_forloeb_profile --existing-config --yes

# Download and install external libraries
docker compose exec phpfpm vendor/bin/drush webform:libraries:download

# Build theme assets
docker compose run --rm node yarn --cwd web/themes/custom/os2forms_selvbetjening_theme install
docker compose run --rm node yarn --cwd web/themes/custom/os2forms_selvbetjening_theme build

# Open the site
open $(docker compose exec phpfpm vendor/bin/drush --uri=http://$(docker compose port nginx 8080) user:login)

Configuration

Some modules included in this project needs additional configuration. Take a look at the following modules on how to configure them:

CPR and CVR lookups

See /admin/config/system/os2web-datalookup/cpr-lookup and /admin/config/system/os2web-datalookup/cvr-lookup for configuration.

OpenID Connect login

The OpenID Connect module is used to authenticate users and for security reasons the module must be configured in the settings.local.php file:

# settings.local.php
$config['openid_connect.client.generic']['settings']['client_id'] = '…; // Get this from your IdP provider
$config['openid_connect.client.generic']['settings']['client_secret'] = '…'; // Get this from your IdP provider
$config['openid_connect.client.generic']['settings']['authorization_endpoint'] = '…'; // Get this from your OpenID Connect Discovery endpoint
$config['openid_connect.client.generic']['settings']['token_endpoint'] = '…'; // Get this from your OpenID Connect Discovery endpoint

// Set Drupal roles from map IdP roles (in the `groups` claim) on authentication.
$config['openid_connect.settings']['role_mappings']['administrator'] = ['AD-administrator'];
$config['openid_connect.settings']['role_mappings']['forloeb_designer'] = ['GG-Rolle-Digitaleworkflows-forloebsdesigner-prod'];
$config['openid_connect.settings']['role_mappings']['flow_designer'] = ['GG-Rolle-Digitaleworkflows-flowdesigner-prod'];

// Overwrite a translation to show a meaningful text on the log in button.
$settings['locale_custom_strings_en'][''] = [
   'Log in with @client_title' => 'Log in with OpenID Connect (employee)',
];

$settings['locale_custom_strings_da'][''] = [
   'Log in with @client_title' => 'Medarbejderlogin',
];

Selvbetjening Module

The OS2Forms Selvbetjening module updates the following:

Webform Email Handler

Adds a translatable description to the message body section.

Webform category

Adds a translatable description to the webform category selects.

Maestro

We use the Maestro module to make workflows.

To avoid having to run the Orchestrator manually, a token must be set in /admin/config/workflow/maestro. The Orchestrator can then be run by visiting https://[site]/orchestrator/{token}. Adding the following cronjob to your crontab will run the Orchestrator every five minutes.

*/5 * * * * /usr/bin/curl --location https://[site]/orchestrator/{token} > /dev/null 2>&1; /usr/local/bin/cron-exit-status -c 'Some exit message probably containing [site]' -v $?

In /admin/config/workflow/maestro you can also configure whether a refresh of the Maestro Task Console should run the Orchestrator, which certainly could be an advantage during tests.

REST API

We use Webform REST to expose a number of API endpoints. See OS2Forms REST API for details.

Production

composer install --no-dev --optimize-autoloader

Install site as described above.

Apply updates by running

vendor/bin/drush --yes deploy

Configure the memcache module: https://git.drupalcode.org/project/memcache/blob/8.x-2.x/README.txt

Production Database

The database of production must never be copied to a local development environment, as its data contains personal data.

If developers need an actual database for local development, the stg-environment can be made ready for download by ensuring that you delete all submissions and other informations that can have personal character, before downloading.

Coding standards

docker compose exec phpfpm composer coding-standards-check

docker compose run node yarn --cwd /app install
docker compose run node yarn --cwd /app coding-standards-check

Testing

Emails

For development, the Mail Debugger module is available:

docker compose exec phpfpm vendor/bin/drush pm:enable mail_debugger
open "http://$(docker compose port nginx 80)/admin/config/development/mail_debugger"
# Open MailHog
open "http://$(docker compose port mailhog 8025)"

Note: Make sure to not add mail_debugger to the modules list in config/sync/core.extension.yml – it’s only for development.

Check your SMTP-settings with

docker compose exec phpfpm vendor/bin/drush config:get --include-overridden smtp.settings

Admin message

An admin message (shown only on admin pages) can be defined in settings.local.php, e.g.:

$settings['os2forms_selvbetjening']['admin_message'] = 'This is a <strong>test system</strong>';
$settings['os2forms_selvbetjening']['admin_message_style'] = 'padding: 1em; background-color: red; color: yellow;';

Translations

Import translations by running

docker compose exec --workdir /app/web phpfpm ../vendor/bin/drush locale:import --type=customized --override=none da ../translations/translations.da.po

Export translations by running

docker compose exec --workdir /app/web phpfpm ../vendor/bin/drush locale:export da --types=customized > ./translations/translations.da.po

Open translations/translations.da.po with the latest version of Poedit to clean up and then save the file.

See https://medium.com/limoengroen/how-to-deploy-drupal-interface-translations-5653294c4af6 for further details.

itk-dev/os2forms_selvbetjening