NHS Digital Website - Hippo CMS
- To setup this project run
make init. - To run an initial build of all modules run
mvn clean verify(only need to do this once). - To start local server
make serve. - To run all tests
make test. - To get more help, simply run
make help.
Key Maven Build Operations
This project uses Maven as its build system. Unless stated otherwise, instructions below assume that Maven commands
will be executed from command line in the directory of the parent module.
The IDE of your choice may offer alternate (sometimes more convenient) mechanisms to execute those or similar
commands, so it's worth spending some time to explore its capabilities. In particular, IntelliJ is able to target
Junit tests without involving Maven, giving a more graphical feedback on the tests' status combined with the ability
to automatically re-run the tests whenever the code changes. It also offers the option of saving commonly used commands
as Run Configurations for quick and easy recall.
Note: whenever you execute an operation that involves starting up the application, make sure you don't have an instance
of it already running in the background or the server will fail to start, complaining about the port being already
used.
To run:
Unit tests:
mvn test
Full suite of tests:
mvn verify -Pacceptance-test-hippo,acceptance-test
This will execute both unit and acceptance tests. An instance of Tomcat server will be automatically spawned and
applications under test deployed into it, prior to executing automated acceptance tests. The server will automatically
stop once the tests complete. Tomcat server gets automatically downloaded and installed in a temporary project space as
part of the build so it doesn't have to already be present in the development system.
Note that, by default, the acceptance tests will be executed in a 'headless' mode, that is no browser window will be
opened on the screen. In order to see the web browser interacted with by the automated accepance tests, disable headless
mode by adding parameter -Dheadless=false in the command line.
Profile acceptance-test activates the tests themselves, while acceptance-test-hippo ensures
automatic startup and shutdown of the application.
Standalone Hippo instance:
mvn verify
mvn -Pcargo.run
This will run Hippo in a standalone mode, useful during development and manual tests. The first line runs unit tests and
packages the application and the second one starts it.
Once the aplication has started, the console will display message Press Ctrl-C to stop the Cargo container.... You can
then access Hippo CMS by navigating to http://localhost:8080/cms in your web browser.
You can stop the server by following the aforementioned message and hitting Ctrl-C in the terminal window where you
started Hippo.
Acceptance tests against standalone Hippo instance
In cases where you only edit code of the acceptance tests (rather than production code), usually a lot of time can
be saved by keeping an instance of the application running in the background and execute acceptance tests repeatedly,
without having to restart the application. To do so, make sure to have the application already started and running in a
standalone mode (see instructions above) and then, to run the tests, execute:
mvn verify -f acceptance-tests/pom.xml -Pacceptance-test
See Automated Acceptance Tests section for more details on how to further optimise the
development cycle when working on acceptance tests.
Auto-export
When making changes to the CMS or console data, you may want your changes to be persisted in the yaml configuration
to be boot strapped into the application on startup. The easiest way to do this is to turn auto-export on in the CMS
(gray button on bottom left of every CMS page) or in the Console (top menu options). Make sure you turn it on before
making any of the changes and turn it off again once you are done. This will produce new/amended yaml files. You should
make sure the changes are in the correct module (application / development) creating a new file for new nodes where appropriate.
YAML Formatter
All the yaml repository data files are formatted with a custom groovy script when the project is built.
This is to make the format consistent so when comparing changes to a previous version it is a lot eaiser
to see what has actually changed. UUIDs are also removed as these are generated by hippo dynamically on start up.
You can run the formatter manually by running make format-yaml.
Updating versions
Periodically the versions of the dependencies we use should be updated to the latest versions, in order to
ensure we have the latest bug fixes and security patches. For the same reason, the version of Hippo that we
use as the parent pom should be updated whenever there is a new release.
To update versions automatically we use the maven versions plugin.
This will automatically update all dependancies and the parent pom version to the latest version avaliable.
To use this, simply run:
make update-dependencies
This will go through all the modules and sub-modules and check for newer versions for any that are specified
in the pom.
Potential issues when upgrading Hippo version
This section should be kept up to date with all known changes we have made to the code base which require
consideration when changing parent Hippo version.
Document Workflow
We have our own version of the Hippo document workflow which is a copy of the out of the box workflow with
some customizations to meet our requirements. When changing hippo version there may be changes to the
document workflow which we need to implement in our forked version.
The original workflow can be sound in the sources jar:
hippo-repository-workflow-[VERSION]-sources.jar/hcm-config/documentworkflow.scxml
Our version is located here:
repository-data/application/src/main/resources/hcm-config/configuration/modules/documentworkflow.scxml
UI development
Development
For best UI developer experience run the local dev server in one Terminal window, and run the SASS or LESS compiler with Maven in another one (remember to 'cd' into the appropriate folder)!
CLI commands
Run LESS compiler watching for local dev
cd repository-data/webfiles
mvn lesscss:compile -D lesscss.watch=true
Run SASS compiler watching for local dev
cd repository-data/webfiles
mvn com.github.warmuuh:libsass-maven-plugin:0.2.8-libsass_3.4.4:watch
Run the local dev server (will throw a lot of Splunk errors)
mvn clean verify && mvn -Pcargo.run -Drepo.path=storage
Run the local dev server with quiet Splunk
mvn -Pcargo.run -Dsplunk.hec.name=localhost -Dsplunk.url=http://localhost -Dsplunk.token= -Drepo.path=storage
Mega command
If you keep switching between different branches, you will have to remove the
storagefolder, then rebuild the app using the storage path and of course you'll want to quietsplunk...
rm -rf storage && mvn clean verify && mvn -Pcargo.run -Dsplunk.hec.name=localhost -Dsplunk.url=http://localhost -Dsplunk.token= -Drepo.path=storage
Both the CMS and the CMS console has their own AutoExport switch, which can be changed separately.
Auto export - on/off
There are 2 ways to run the server: with or without autoexport. When the app runs with autoexport on, it exports new- and updated files triggered by CMS content updates and additions. To avoid these files accidentally being tracked by git, you better run the app without autoexport.
About the SASS compiler
The most up to date Maven LibSass plugin is this one. The latest version as of 16/01/2018 is 0.2.8 (important to know what version is currently used in the project because it has to be specified in both the
pom.xmlfile and in the command line).
Front-end library
We're using the NHS Digital UI library as a base for our UI components and styling. The currently available release (0.8.0) is used as described in the documentation.
Running the project for the first time
You'll need a couple of things in place to be able to successfully run the project, you can find the details here
Testing local site on VMs
In order to be able to test your localhost from a VM (such as VirtualBox) you'll have to add your IPv4 address to the server configuration. You can read how it can be done here
Adding test content
Check out the What if I want to add test content section for details
Valtech branching strategy
Valtech follows RPS's rebase strategy - working off master branch. Once a feature branch is complete, we squash all commits on it into 1 meaningful commit and make a PR.
Step 0 - Checkout master branch
git checkout master
git pull --rebase origin master
Step 1 - Create new feature branch
git branch DW-XX-my-feature
git checkout DW-XX-my-feature
Make changes, create new commits, work work work...
Step 2 - Push work to remote and keep it in line with origin
git pull --rebase origin DW-0000-feature // pull latest updates of the branch from origin
git push origin DW-0000-feature // push new commits to origin (might need to force push)
Step 3 - Once Feature is complete, squash the commits into 1 meaningful commit and make a PR to the master branch
git fetch
git rebase -i origin/master
git push origin DW-0000-feature // again - might need to force push
Automated Acceptance Tests
Automated acceptance tests ensure that the implementation meets functional criteria specified in the requirements.
Framework used in this project to run these tests is Cucumber-JVM and the tests are specified as BDD-style
scenarios, written in a language called Gherkin; see the language's reference for guidance on syntax.
See Key Maven Build Operations for instructions how to execute the automated acceptance
tests.
Run Only Selected Scenarios
When you work on scenarios covering a specific feature, you don't always have to, or want to, run all the acceptance
tests in the system. In such a case, you can speed up improve your change-the-test-code/run-the-tests cycle by only
running selected Cucumber scenario(s) rather than all.
To do that:
- tag selected scenario(s) with a custom tag
@WIP, placing it in the line directly preceding
the scenario. - run
make test.wipthis will run only the scenarios you have tagged.
Remember to remove these custom tags before executing a final complete suite of tests and
before pushing your changes to the central repo.
More details
This Maven project has been generated using the official Hippo Maven project archetype v12.1.0.
Most of the project's structure has been retained with the few custom modifications described in the sections above
but you can find more details in the original README files auto-generated by the archetype:
What if...?
If you have a development related question, it's possible that we already have a
answer in What If section