The base application on Acquia Cloud for the University of Iowa.
This project is based on BLT, an open-source project template and tool that enables building, testing, and deploying Drupal installations following Acquia Professional Services best practices. While this is one of many methodologies, it is our recommended methodology.
- Review the Required / Recommended Skills for working with a BLT project.
- Ensure that your computer meets the minimum installation requirements (and then install the required applications). See the System Requirements.
- 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 blt dsa or ddev composer install.
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.
Make sure you have an Acquia Cloud key and secret saved in the blt/local.blt.yml file. This file is ignored by Git. Be sure you do not accidentally commit your credentials to the blt/blt.yml file which is tracked in Git. Do not share your key or secret with anyone.
uiowa:
credentials:
acquia:
key: foo
secret: bar
Set the multisites that you want BLT to sync by default:
multisites:
- default
- bar.uiowa.edu
- foo.uiowa.edu
Multisites will not be able to bootstrap without a local.settings.php file. The blt:init:settings (or bis for short) command will generate local settings files only for the multisite defined in BLT configuration. By default, this is all multisites but be aware that the local.blt.yml change documented above will override that. You can temporarily remove that override if you need to generate settings files for all multisites.
The blt frontend command will install and compile frontend assets.
Local configuration overrides can be set in the local.settings.php file for each multisite. For example, to configure stage file proxy:
$config['stage_file_proxy.settings']['origin'] = 'https://mysite.com';
$config['stage_file_proxy.settings']['hotlink'] = TRUE;
There are a few custom BLT commands to manage multisites. Run blt list uiowa to see all the commands in the uiowa namespace. Then run blt CMD --help for more information on specific commands.
Because the .git directory is not synced to the web container, some commands need to be run on your host machine instead. You can run ./vendor/bin/blt from the project root or install the BLT Launcher to just run blt.
Please note this approach is not yet tested nor recommended.
If an individual site wants to export ALL of its configuration and manage it going forward, an include setting with the following should accomplish that:
$blt_override_config_directories = FALSE;
$settings['config_sync_directory'] = DRUPAL_ROOT . '/config/' . $site_dir;
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 blt dsa. 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. BLT may download default config files that we don't use like docroot/sites/default/default.services.yml. Different updates may require difference procedures.
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 blt dsa to check for any further config discrepancies. If there are none, proceed with code deployment as per usual.
Testing a uids change in uiowa:
- Update the hash with the uids commit you wish you test in the uids_base package.json file: "@uiowa/uids": "uiowa/uids#[Enter hash here]"
- Then run
yarn upgrade @uiowa/uids rm -rf ./node_modulesyarn cache cleanyarn installyarn workspace uids_base gulp --development
Follow the drupal/core-recommended instructions on updating.
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/cshs | No stable release since fe1b07101d724e6aa5fbcd78c50ce2780534ed0f |
| drupal/lb_direct_add | No 2.x stable release. |
| drupal/menu_link_weight | No stable release since f4a4b71b. |
| drupal/photoswipe | Need 71e54fbcca748c7ec2cfc3d2fdd92c9a180b5852. No stable release with patch |
| drupal/redirect | Need e5201ca5 from 8.x-1.x branch plus a patch. https://git.drupalcode.org/project/redirect/-/commits/8.x-1.x |
| drupal/reroute_email | No stable release since 438a67caeb0b0cc47d1deb0cee50afda9a907dc8 |
| kartsims/easysvg | Need kartsims/easysvg#27 which is not included in a release. |
| uiowa/block_content_template | Forked from a deprecated project. |
| dompdf/dompdf | https://www.drupal.org/project/entity_print/issues/3169624 |
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 BLT documentation may be useful. You may also access a list of BLT commands by running this:
$ blt
Most of the BLT commands referenced above have shorthand aliases. Check the output of blt for details.
You can also run blt commands on an Acquia Cloud environment, but you must run them using the path and from the app root. ./vendor/bin/blt my:blt:command foo
BLT projects are designed to instill software development best practices (including git workflows).
Our BLT Developer documentation includes an example workflow.