When and if a new environment is setup on Acquia for CoB, the following steps should be followed:
When a new environment is added, it will have a 3-4 character name (e.g. uat
or dev2
etc). This checklist refers to this environment short-name as the envname.
This change adds the specified domains to the acquia-purge registry. This means the varnish cache for these domains will be automatically purged. If a sub-domain is attached to an environment and is NOT listed here, then it will not be automatically purged as content is changed.
This change directs the new environment to request images and files from a shared (linked) folder rather than the default sites/default/files
folder. The folder is linked to conserve file space as each environment basic requires the same sets of images and files.
The following steps need to be completed to allow single sign on via Ping Federated.
To use the environment as a Drupal site, you need to attach a branch from the Acquia git repository. For detailed instructions see On Demand section.
Attach a GitHub branch to an Aquia environment.
On demand instances of the Drupal site (boston.gov) are useful to demonstrate new features or functionality sand-boxed away from the continuous-deployment process.
These on demand versions of boston.gov are designed to be housed on a near-duplicate environment to the production site, and be easily accessible in a normal browser from anywhere by people with the correct link.
Acquia provide 6 environments to CityOfBoston.
The dev, stage(test) and prod
environments are associated with git branches used in the continuous-deploy workflow and can not be attached to different branches or repository tags without disrupting and potentially breaking the workflow.
The dev2, dev3, ci and uat
environments can track any desired branch or tag (even develop-deploy
or master-deploy
) without disrupting the continuous-deployment workflow.
This process has been decommissioned and some of the processes below are no longer implemented in scripts.
This page is left here only to provide background should COB decide/require to have Drupal in an AWS managed container.
You can push your local repository up to a test instance on our staging cluster on AWS. This will let you show off functionality using data from a staging snapshot of Boston.gov.
You will need a full development environment and Drupal 8 installed on your local machine (refer to earlier notes).
Install the AWS Command Line Interface.
Get a “CLI” IAM user with an access key and secret key.
Use aws configure
to log your CLI user in locally. Use us-east-1
as the
default region.
Request your CLI IAM user credentials from DoIT.
To create a place to upload your code, follow the instructions in the CityOfBoston/digital-terraform repository to make a “variant” of the Boston.gov staging deployment.
To push your local repository up to the cluster, run:
Where <variant>
is the variant name you created in CityOfBoston/digital-terraform
.
This will build a container image locally and upload it to ECR. It will then update your staging ECS service to use the new code.
By default, the container startup process will initialize its MySQL database with a snapshot of the staging environment from Acquia.
After the container starts up and is healthy, the doit
script will print useful URLs and then quit.
Direct SSH access is not generally available on the ECS cluster. To run drush
commands on your test instance, you can visit the webconsole.php
page at its domain. This will give you a shell prompt where you can run e.g. drush uli
to get a login link.
The webconsole.php
shell starts in docroot
.
Talk to another DoIT developer to get the webconsole username and password.
NOTE: Each time you deploy code to your test instance it starts with a fresh copy of the Drupal database.
If you want to preserve state between test runs, log in to webconsole.php
and run:
(The ..
is because webconsole.php
starts in the docroot
.)
This will take a snapshot of your database and upload it to S3. The next time your test instance starts up, it will start its sync from this database rather than the Acquia staging one.
The database will also be destroyed when the AWS containers are restarted for any reason. It is good practice to stash your DB regularly.
To clear the stash, so that your database starts fresh on the next test instance push, use webconsole.php
to run:
Here is a snapshot of the doit script referred to above.
Elsewhere this might be termed spinning up an on-demand instance of the site.
Make sure you have the latest copy of the main Drupal 8 repository cloned to a folder <repo-root-path>.
Checkout the branch develop
and make sure the latest commits are pulled (fetch+merged) locally.
Commit your work to a new branch (on-demand-branchname
) off the develop
branch .
Push that branch to GitHub, but do not create a PR or merge into develop
.
Edit <rep-root-path>/.travis.yml
file and make the following additions:
(Note: replace <on-demand-branchname>
with on-demand-branchname
.)
Edit <rep-root-path>/scripts/.config.yml
file and make the following additions:
(Note: This partial example addition is configured to deploy to the Ci environment on Acquia)
(Note: replace <on-demand-branchname>
with on-demand-branchname
.)
Commit the .config.yml and .travis.yml
changes to on-demand-branchname
and push to GitHub - but do not merge into develop
.
Make a small inconsequential change to the code and commit to the on-demand-branchname
branch, and push to GitHub. This will cause the first-time build on Travis, and deploy into the on-demand-branchname-deploy
branch in the Acquia Repository.
The Travis build can be tracked here in Travis.
Login to the Acquia Cloud console. In the UI switch the code in the Ci/Uat environment to the on-demand-branchname-deploy
branch.
This will cause a deploy on the Acquia server, which will copy across the current stage
database and update with configuration from the on-demand-branchname
branch.
The "on-demand" environment is now set. Users may view and interact with the environment as required. See Notes in "gotcha's" box below.
Once you have finished the demo/test/showcase cycle, you can merge the on-demand-branchname
branch to develop
- provided you wish the code changes to be pushed through the continuous-deploy process to production
.
Finally you can detach the on-demand-branchname
branch from the Acquia environment, and set it back to the tags/welcome
tag.
You can direct users to the URL's below, select the environment you switched to the on-demand-branchname-deploy
branch (in step 8) from the table below.
Housekeeping.
When finished with the environment, you should consider rolling-back the changes you made to .travis.yml
and .config.yml
in steps 4 & 5 before finally merging on-demand-branchname
to develop.
It is likely that the on-demand instance is no longer required, and its unnecessary for the the on-demand-branchname
to be tracked by Travis.
Also as a courtesy, change the branch on the environment back to tags/WELCOME
so it is clear that the environment is available for use by other developers.
Updating: If you push changes to on-demand-branchname
in GitHub (which eventually causes Acquia'son-demand-branchname-deploy
to be updated) - then in Aquia's terminology you are "updating" the code.
Any commits you push to the GitHubon-demand-branchname
will cause Travis to rebuild and update the code on the Ci/Uat environment and this will cause Acquia'spost-code-update
hook script to run.
- That update-hook script will backup your database and update and new configurations but will not update or overwrite any content (so changes made by users will be retained).
Deploying: If you switch the code on the Acquia server from on-demand-branchname-deploy
to some other branch or tag, and then back again - then in Acquia's terminology each switch of branch is a "deploy" of the code. GitHub is not affected by this change, so nothing will run on Travis, but once each switch is complete, Acquia'spost-code-deploy
hook script will run.
- That deploy-hook script will sync the database from the stage
environment and will overwrite any content in the database. Therefore, any content previously added/changed by users will be lost.
Environment
URL
uat
(public DNS entry)
ci
(public DNS entry)
dev2
(no DNS - make entry in local hosts file)
dev3 (pending)
https://d8-dev3.boston.gov
(no DNS - make entry in local hosts file)