The base application on Acquia Cloud for the University of Iowa.
This README covers setup, local development and dependency updates. Check the table below for additional information.
| Doc | Topic |
|---|---|
| sitenow/README.md | The ./sn CLI |
| config/README.md | Configuration management |
| config/features/README.md | Feature splits |
| docroot/modules/README.md | Custom and contributed modules |
| patches/README.md | Patching contrib and core |
| drush/README.md | Drush configuration and aliases |
| scripts/ci/README.md | Continuous integration checks |
| tests/README.md | Automated tests |
This project uses Acquia Drupal Recommended Settings for its settings.php cascade, and a custom Symfony Console application (./sn, in sitenow/) for multisite provisioning, deployment, and reporting.
- Ensure that your computer meets the minimum installation requirements for DDEV.
- Request access to organization that owns the project repo in GitHub (if needed).
- Request access to the Acquia Cloud Environment for your project (if needed).
- Setup a SSH key that can be used for GitHub and the Acquia Cloud (you CAN use the same key).
- Clone the repository. By default, Git names this "origin" on your local.
$ git clone git@github.com:uiowa/uiowa
Ddev is used for the local environment. Follow their docs to get it installed. Once installed, read up on basic CLI usage to understand how to manage the containers.
Once installed and started, you can either ddev ssh and run non-ddev CLI commands there, or run them on your host with ddev CMD. For example, ddev sn sync:all or ddev composer install.
The Node.js version is set in .nvmrc and should match nodejs_version in .ddev/config.yaml. CI reads .nvmrc.
Yarn workspaces can be defined in the top-level package.json file. Each workspace can depend on other workspaces as well as define their own build script. You can run workspace build scripts on the web container with ddev yarn workspace WORKSPACE_NAME run SCRIPT_NAME. Every workspace build script gets run during continuous integration to build assets. The build assets are committed to the build artifact and deployed.
Workspaces that need to leverage uiowa/uids assets should depend on uids_base and not uiowa/uids directly. This is to ensure the version of uiowa/uids is strictly managed and because uids_base runs a build script that copies necessary assets into the build artifact. For example, fonts are available in uids_base which would not be available in the excluded node_modules directory.
Ddev creates a database container that is accessible from the web container. You can access the database container from your host as well using tools like SequelPro or TablePlus.
As long as a site has a local settings file, it should be configured to show all warnings and errors to the screen. Other log messages can be viewed by running ddev logs.
Save your Acquia Cloud key and secret in ~/.sitenow/credentials.yml. This file lives in your home directory rather than the repository so it can never be committed. Do not share your key or secret with anyone.
acquia:
key: foo
secret: bar
Set the sites you work with locally in sitenow/local.sites.yml. This file is ignored by Git. It is the list ddev sn sync:all syncs and ddev sn umi installs, and it can be overridden per-run with --sites.
sites:
- default
- bar.uiowa.edu
- foo.uiowa.edu
Multisites will not be able to bootstrap without a local.settings.php file. The drush settings --uri=SITE command (provided by Acquia Drupal Recommended Settings) will generate local settings files for a multisite.
Local overrides go directly in that site's docroot/sites/SITE/settings/local.settings.php, since it is not tracked in git. For example, to configure stage file proxy ($config['stage_file_proxy.settings']['origin'] = 'https://sandbox.prod.drupal.uiowa.edu';) add that line to the file directly.
The ddev yarn frontend:build command will install and compile frontend assets.
SiteNow provides host-side multisite commands through the sn CLI, including multisite:create. See sitenow/README.md.
Run sn from your host. A few commands act on a site's local database, which only exists in the web container, so run those as ddev sn. ./sn list marks them (ddev required).
Before starting updates, make sure your local environment is on a feature branch created from the latest version of the default branch and synced with production by running ddev sn sync:all. After updating, certain scaffold files may need to be resolved/removed. For example, the htaccess patch might need to be regenerated if it does not apply to the new .htaccess file. Drupal core scaffolding may download default config files that we don't use like docroot/sites/default/default.services.yml. Different updates may require difference procedures.
- Remove the
core_htaccess.patchline frompost-drupal-scaffold-cmdin the composer.json file and runddev composer install. - Commit the .htaccess change only with git but do not push.
- Re-add the line back to composer and re-run
ddev composer install. - Make edits to the .htaccess file.
git diff docroot/.htaccess > patches/core_htaccess.patch- Commit both the changed version and the patch. Push.
- Same method works for robots.txt and development_services.
Configuration tracked in the repository will need to be exported before deployment. To ensure configuration is exported correctly, manually sync a site from production using Drush. Then run database updates and export any configuration changes. Add and commit the config changes and then run another ddev sn sync:all to check for any further config discrepancies. If there are none, proceed with code deployment as per usual.
- Update the hash with the uids commit you wish you test in the uids_base package.json file: "@uiowa/uids4": "uiowa/uids4#[Enter hash here]"
- Then run
yarn upgrade @uiowa/uids4 rm -rf ./node_modulesyarn cache cleanyarn installyarn workspace uids_base gulp --development
Run the update hooks against a database built under the old code, the way a deploy hits production:
- On
main, runddev composer install. - Sync the site:
ddev sn ds <site>. - Check out the feature branch and run
ddev composer installagain. - Run
ddev drush @<id>.local updb -y. - Export and commit any config the update changed, per Configuration changes above.
Syncing after the branch is checked out would test the update hook against a database that already has the new schema, which is not what a deploy does.
Run composer update "drupal/core-*" --with-all-dependencies.
You can run composer update package/name to update additional dependencies. The output from the Composer commands can be used as the long text for commit messages. Ideally, each package update would be one commit for clarity and easier reverting.
The packages below are locked at specific SHAs and will not update using the method described above. They should be periodically checked for new stable releases and updated, if viable.
| Package | Reason |
|---|---|
| drupal/theme_permission | Using D10 compatibility patch that is compatible with dev version. Waiting for D10 release. |
Redirects can be added to the docroot/.htaccess file. The .htaccess file be will deployed to all applications, regardless of the domain. Therefore, creating per-site redirects using the Redirect module is preferred.
Note that too many .htaccess redirects can incur a performance hit. See the Acquia redirect documentation for more information and examples.
Ideally, redirects in .htaccess would only exist temporarily. Check the commit history of that file using a command similar to: git log --before="6 months ago" --grep="redirect" -- docroot/.htaccess to see how old a redirect is.
Additional Acquia Drupal Recommended Settings documentation may be useful for the settings.php cascade. See sitenow/README.md for the ./sn command reference.