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
Follow the BLT docs to get started wit DrupalVM.
All BLT commands should be run on the VM. You can SSH into the VM using vagrant ssh. See the Vagrant docs for basic CLI usage.
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 VM with yarn workspace WORKSPACE_NAME run SCRIPT_NAME. Every workspace build script gets run during continuous integration to build assets. The build assets are co
8000
mmitted 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.
Note that certain filesystem watch commands are either slow or broken over Vagrant synced folders. To get around this, you can run workspace build scripts manually or run watch commands on your host although you'll need Node, NVM and Yarn. Once installed, you can run the following from the application root:
nvm install
nvm use
If you're watching SASS and compiling it, you'll need to rebuild node-sass bindings for your host OS.
npm rebuild node-sass
This should not result in any changes to yarn.lock. If you try to compile back on the VM, you may need to rebuild it there or run blt frontend again to match production. Note that you do not need to use NVM on the VM - it is not installed.
Use SequelPro to connect to DrupalVM.
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, like watchdog, can be viewed by tailing the syslog: sudo tail -f /var/log/syslog | grep drupal. PimpMyLog is also available at https://pimpmylog.local.drupal.uiowa.edu but requires more configuration to work with syslog.
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
The drupal:sync:all-sites command will generate settings files only if they do not exist. If you want to re-generate all multisite local settings files, you can run rm -f docroot/sites/*/settings/local.settings.php beforehand.
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;
To add a new site to the project, run the following command:
blt umc example.uiowa.edu
Replace example.uiowa.edu with the URI of the site you are creating.
The following options can also be passed in:
--requester=hawkid- Use the hawkid of the person who requested the site. Will be given webmaster access when installed.--no-db- Do not create remote databases.--no-commit- Do not create a new commit in git.--simulate- Only runs the commands associated withblt recipes:multisite:init.
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/layout_builder_shortcuts | No stable release. |
| drupal/lb_direct_add | No stable release. |
| drupal/redirect | Need e5201ca5 from 8.x-1.x branch plus a patch. https://git.drupalcode.org/project/redirect/-/commits/8.x-1.x |
| 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.