End-user documentation for the BAS Style Kit.
Details what it is and how to use it to build websites and applications. Built as a static website using Jekyll.
See the relevant documentation for how documentation is organised and managed:
These instructions show how to setup a development environment for the Style Kit documentation.
Source code is available from two repositories:
- BAS GitLab (canonical, private)
- BAS GitHub (read-only mirror, public)
To create a local development environment using the GitLab repository [1]:
$ git clone https://gitlab.data.bas.ac.uk/web-apps/bsk/bas-style-kit-docs.git
$ cd bas-style-kit-docs/
$ docker-compose pull
$ docker-compose up
To create a local development environment using the GitHub repository:
$ git clone https://github.com/antarctica/bas-style-kit-docs.git
$ cd bas-style-kit-docs/
$ docker-compose build
$ docker-compose up
This will launch a single container to build the site using jekyll serve, with incremental building enabled.
Visit localhost:9000 to access a local version of the documentation site.
[1] If you have access to the BAS GitLab instance, you will need to authenticate to use the BAS private Docker registry initially:
$ docker login docker-registry.data.bas.ac.uk
To simulate a production build of the documentation site, add this environment variable to the app service in
docker-compose.yml:
---
version: '2'
services:
app:
...
environment:
- JEKYLL_ENV=productionNote: You will need to delete site/_site/ to force a global site rebuild, as incremental building is enabled.
graph TD
A(Work on CSS & JS) --> B
B[Style Kit Core <br> https://gitlab.data.bas.ac.uk/web-apps/bsk/bas-style-kit] --> |Include assets directly or via the BAS CDN| G
D(Work on website partials)--> E
E[Style Kit - Jekyll Theme <br> https://gitlab.data.bas.ac.uk/web-apps/bsk/bas-style-kit-jekyll-theme] --> |Ruby Gem hosted at https://rubygems.org| G
G[Style Kit Docs <br> Jekyll webpages for this project] --> |Create new Docker Image & push to BAS GitLab Docker registry <br> Git push to master branch| I
I[Deploy to Staging <br> style-kit-testing.web.bas.ac.uk] --> |Create a new GitLab tag| J
J[Deploy to Production <br> style-kit.web.bas.ac.uk]
If new Gem dependencies are introduced, the project Docker image will need to be rebuilt and pushed to the private BAS
Docker Repository [1]. A new Gemfile.lock file will also need to be generated for use with
Dependency vulnerability scanning.
The current date is used as part of the project Docker image tag to ensure the latest version is used by all developers.
Before rebuilding this image you MUST update this tag value in docker-compose.yml and .gitlab-ci.yml first.
# build image to install updated dependencies
$ docker-compose build app
$ docker-compose push app # gets the date from the tag used in the docker-compose.yml
# copy Gemfile.lock into project from the updated image
$ docker-compose run --entrypoint="" app ash
$ cd ..
$ bundle install
$ mv Gemfile.lock site/
$ exit
$ docker-compose down
$ mv site/Gemfile.lock ./[1] You will need to authenticate to use the BAS private Docker registry initially:
$ docker login docker-registry.data.bas.ac.uk
The BAS GitLab instance is used for
Continuous Integration using settings defined
in .gitlab-ci.yml.
- Update the tags (using the date method described in Updating dependencies for the docker image in both the docker-compose.yml & the gitlab-ci.yml
- it is likely that the docker images will need to be updated. The following commands should make that process easy:
# build and use a new docker image to deploy changes
$ docker-compose build app
$ docker-compose push appAlternatively manually tagging and pushing the new image will work as well. The current date is used as part of the project Docker image tag to ensure the latest version is used by all developers.
Before rebuilding this image you MUST update this tag value in docker-compose.yml and .gitlab-ci.yml first.
The BAS GitLab instance is used for
Continuous Deployment using settings defined in
.gitlab-ci.yml.
Changes pushed to the master branch will be available at: https://style-kit-testing.web.bas.ac.uk.
Tagged commits will be available at: https://style-kit.web.bas.ac.uk.
Note: Due to caching, deployed changes may not appear for up to 1 hour.
There is only one long-term branch in this repository, master, which represents a working, stable, version of the project, but is not necessarily the released version.
All changes are made in other branches and merged into the Master branch when ready. Multiple branches may be active at any one time, and MUST therefore be rebased on master before they are merged.
When required, a release is made using a release branch. This is then merged with master and tagged. This triggers the relevant deployment tasks to release a new version.
Git, Terraform and permissions to the BAS AWS environment are required to provision resources for this project.
$ git clone https://github.com/antarctica/bas-style-kit-docs.git
$ cd bas-style-kit-docs/provisioning/terraform
$ docker-compose run terraform
$ terraform init
$ terraform validate
$ terraform fmt
$ terraform apply
$ exit
$ docker-compose down
During provisioning, an AWS IAM user will be created with least-privilege permissions to enable Continuous Deployment.
Access credentials for this user will need to generated manually through the AWS Console and set as secret variables
within GitLab. See the .gitlab-ci.yml file for specifics on how to do this.
Note: Commit all Terraform state files to this repository.
This project uses issue tracking to manage development of new features/improvements and reporting bugs.
The maintainer of this project is the BAS Web & Applications Team, they can be contacted through the BAS Service Desk
The vast majority of this project is based on the Bootstrap project.
50% of any credit for this project should go to Boostrap's authors and contributors.
This project is a derivative of the Bootstrap framework and includes additional code unique to this project.
See Licence.md for more information.