CitySpace is the City of Austin employee intranet. It uses the Drupal 8 CMS and is deployed on Acquia Cloud using a Lightning distribution.
1. Set up your Acquia Cloud account
Request an invitation to the CitySpace project on Acquia Cloud
Copy your SSH public key and add it to your Acquia Cloud account
$ pbcopy < ~/.ssh/id_rsa.pub
Confirm the SSH key is configured (you may have to wait several minutes for your key to propagate)
$ ssh firstname.lastname@example.org Your Hardware Enablement Stack (HWE) is supported until April 2017. Welcome to Acquia Cloud. For information about shell access on this server, please see: https://docs.acquia.com/acquia-cloud/ssh Usage may be monitored and audited. austin1@staging-16599:/mnt/gfs/home/austin1$ # Exit the shell austin1@staging-16599:/mnt/gfs/home/austin1$ exit logout Connection to staging-16599.prod.hosting.acquia.com closed.Clone the Github repository
- Request a Drupal Admin account on the Acquia server and follow the invitation instructions. This step must be completed before you download the database and upload it to Dev Desktop
2. Clone the repository
$ git clone email@example.com:cityofaustin/cityspace.git
3. Add Acquia as a remote
$ cd cityspace/ $ git remote add acquia firstname.lastname@example.org:austin1.git
4. Install and configure local environment
Install dependencies We require several gems for CSS management. Use bundler to install them.
# If you don't have bundler yet, install it $ gem install bundler # Once bundler is installed: $ cd docroot/themes/coa_intranet $ bundle install
Download and install Dev Desktop (“DD”) from https://dev.acquia.com/downloads.
- Set “Desktop sites folder” to wherever you save your local projects
- After installation, deselect “Launch Acquia Dev Desktop” and click “Finish”.
- Note that if you have an older version of Drush installed (for example, if you installed it as part of our work on the Drupal 7 AustinTexas.gov) you might need to unlink that older version of drush for this project.
Download the drush aliases file from Google Drive and move it to the
$ mv ~/PATH/TO/DOWNLOADED/austin1.aliases.drushrc.php ~/.drush/
Download the Acquia Cloud database to your Desktop.
$ cd MY_PROJECT_DIRECTORY/ $ drush @austin1.prod sql-dump > ~/Desktop/local.sql
You can specify a different destination path - The important thing is to download it outside of your project directory so that it does not get added to the git repository.
Launch DevDesktop and select “Start with an existing Drupal site located on my computer”.
- Set the “Local codebase folder” to the
docroot/directory in the CitySpace project.
- Set the “Local site name” to “austin1”.
- Under the database dropdown select “Start with MySQL database dump file” and upload the
local.sqlfile you downloaded earlier.
- Set the “Local codebase folder” to the
Ensure Dev Desktop is running (green lights next to “Apache” and “MySQL”) and click on the “Local site” link to ensure your local server can serve the homepage.
Sign In using the same credentials you established for your Drupal Admin account.
Due to some tech and resourcing constraints, CitySpace is not configured for continuous integration. Supporing CI would require an additional layer of Drupal + Acquia configuration that we decided was not worth it during early development stages. In the future, however, this might be re-visited with our Acquia Technical Account Manager.
- URL: alpha.cityspace.austintexas.gov
- Acquia: Prod
- Deployment: Whenever somone accepts & merges a Pull Request (or batch of PRs) into
masterthey should pull the updated branch onto their local machine and then manually initiate a deploy.
$ git checkout master $ git pull $ git push acquia master # Run any drush scripts as necessary: # (Must be in docroot/) $ cd docroot/ # Apply updates to config database from yml files $ drush @austin1.prod config-import active # Apply any pending database and entity schema updates $ drush @austin1.prod updb --entity-updates # Clear cache $ drush @austin1.prod cr
Description: This is not meant to be a stable branch, but instead a way for developers to test their work in an environment that more closely matches
Prod. As a result, it will be regularly destroyed and re-cloned from
Before pushing to
Testplease confirm with the
#cityspace-devSlack channel that nobody else is actively using it to test their own feature branch(es).
The deployment process is similar to
Prod but with a couple of exceptions.
austin1.prodfor your Drush command
- Push to
acquia testrather than
- Instead of PRing into
testyou might choose from 2 alternatives:
testlocally and deploy from test
- Push my-feature as test
$ git push acquia my-feature:test
- You might need to do a force push if whatever was previously on
Testis out-of-sync with the history in your feature branch
$ git push acquia test —force^ note that
forceis preceded by two dashes
-, which may appear in this doc as a single dash depending on what you’re using to view this markdown file
The various style specifications in
/docroot/themes/coa_intranet/assets/_scssare aggregated by
styles.scssand then compiled by Compass into a single, minified stylesheet at
/docroot/themes/coa_intranet/assets/css/styles.css. This file, as defined in coa_intranet.libraries.yml, gets served to the browser.
In order to observe CSS changes in realtime you need to have Compass running in the background.
$ cd docroot/themes/coa_intranet # Tell Compass to listen for changes to the Sass directory (specified in config.rb) $ compass watch >>> Compass is watching for changes. Press Ctrl-C to Stop. # Edit a file in the _scss/ directory, then save it. Any compile errors will be displayed here. >>> Compass is watching for changes. Press Ctrl-C to Stop. modified assets/_scss/cityspace/_overrides.scss write assets/css/styles.css
Acquia Cloud does not support asset precompiling on the server, so assets must always be precompiled to
css/styles.cssbefore being deployed. This should not be a problem so long as you running the listener during your CSS development. However, if someone else has pushed an update to the precompiled
css/styles.cssyou will almost certainly hit a merge conflict when you try to merge.
Resolving a merge conflict on css/styles.css
It’s recommended that you do not include styles.css in your commit and Pull Request. Instead, follow this workflow:
- Add and commit all of your
SASSas you normally would, but do not include
- Get your feature branch merged into
masterinto your local
$ compass compilein your SASS directory in order to force an update to the compiled CSS
css/styles.cssin a new commit titled “Precompile CSS” (no description required), and push that new commit directly back to
You: But Matt, we’re NEVER supposed to commit directly to
master! What gives?
Matt: Yeah I know. It’s the best I could think of. Sorry!
- Add and commit all of your
Useful Drush commands
# Pull production database to test: $ drush sql-sync -vv @austin1.prod @austin1.test # Pull production database to local: $ drush sql-sync -vv @austin1.prod @loc.austin1
# Pull production files to local: $ drush rsync @austin1.prod:%files sites/default/
Apply updates to config database from yml files $ drush @austin1.prod config-import active # Apply any pending database and entity schema updates $ drush @austin1.prod updb --entity-updates # Clear cache $ drush @austin1.prod cr
# Enables downloaded module if found, otherwise prompts to allow download of the latest recommended version & dependencies $ drush en [module] # Uninstall module $ drush pmu [module]
Follow the workflow. Do your work in a feature branch, open a PR for review by the team, and make sure your commit history is clean and deliberate before considering your branch ready for merge.