Contributing > Build Environment




We use jekyll to build static assets for this set of webpages. If you want to help edit or contribute to this site, you probably need to set jekyll up. We also discuss the draft and production build pipeline, which you shouldn’t need to alter.

Cloning the Site Repository

You can get the code for cfsite on bitbucket:

https://bitbucket.org/circleresearch/cfsite

To clone (using ssh) into some folder issue the command

$ git clone git@bitbucket.org:circleresearch/cfsite.git folder

Installing jekyll Locally (on Mac OSX)

The instructions here may not work out-of the box. We recommend running

$ brew install ruby
...
$ /usr/local/opt/ruby/bin/gem install --user-install bundler jekyll

to install a recent version of ruby and subsequently install bundler and jekyll using that install. Then add the following

# jekyll setup requires...                                   
export PATH=/usr/local/opt/ruby/bin:$PATH
export PATH=$HOME/.gem/ruby/2.6.0/bin:$PATH
alias gem=/usr/local/opt/ruby/bin/gem

at the end of ~/.bashrc and

# anything in bashrc                                      
[ -r ~/.bashrc ] && source ~/.bashrc

at the end of ~/.bash_profile. To check that this worked, run

$ source ~/.bashrc
$ jekyll serve

which should run without errors.

You will also need to update bundler, with

$ sudo gem install rubygems-update
$ sudo gem --update system
$ sudo bundle update --bundler

Running jekyll Locally

You should be able to run jekyll locally with this repo. From the cfsite directory, run

cfsite$ bundle exec jekyll serve

Obviously this is after installing and setting up dependencies as described above. This should build the site locally and serve it via http at localhost:4000. Whenever you alter files jekyll will rebuild and you can reload the page in a browser to see the updates. Super convenient for editing.

Drafts Build Pipeline

The cfsite repository contains a bitbucket-pipelines.yml file describing how bitbucket will deploy into a “drafts” environment on any push to the repo. Thats right, any push, from any branch. For this reason it is important to test locally, as described above.

This “default” build pipeline consists of three steps:

Build the site with jekyll

The pipeline first builds the site with jekyll in a ruby docker container image by running the script

bundle install --path vendor/bundle
bundle exec jekyll build --destination cfsite
mkdir -p dist
tar -czvf dist/cfsite-$BITBUCKET_BUILD_NUMBER.tar.gz -C cfsite .

This step also “caches” bundler as vendor/bundle, and stores

dist/cfsite-$BITBUCKET_BUILD_NUMBER.tar.gz

as an “artifact”. Caching means we don’t have to “rebuild” the ruby dependencies for the build process each time we push, and using an artifact allows this (small) archive to be available to later build steps. See the links for more information.

Deploy the Site Archive to S3

For record keeping, we also store the archive in S3 using the “pipe”

- pipe: atlassian/aws-s3-deploy:0.2.4
	variables:
	  AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
	  AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
	  AWS_DEFAULT_REGION: $AWS_BUCKET_REGION
	  S3_BUCKET: $AWS_S3_BUCKET
	  LOCAL_PATH: "dist"

This particular pipe is available here. Note the use of environment variables. We specify these in the Repository Variables section of the repository’s pipelines settings. Specifically,

AWS_BUCKET_REGION = us-west-2
AWS_S3_BUCKET = cloudforest-website/drafts

and the credentials are for a user with (only) write access to this bucket.

Deploy to a Hosting Machine

Finally we need to deploy the built site, encapsulated in the archive

dist/cfsite-$BITBUCKET_BUILD_NUMBER.tar.gz

to a hosting machine. This is done with the third step which executes the script

mkdir -p cfsite
tar -xzf dist/cfsite-$BITBUCKET_BUILD_NUMBER.tar.gz -C cfsite
echo ${HOSTER_SSH_USER}@${HOSTER_SSH_HOST}:${HOSTER_WWW_ROOT}
scp -r cfsite/* ${HOSTER_SSH_USER}@${HOSTER_SSH_HOST}:${HOSTER_WWW_ROOT}

in a docker container with Atlassian’s latest default image. The variables are, again, stored as Repository Variables:

HOSTER_SSH_USER = ubuntu
HOSTER_SSH_HOST = cloudforest.gsbdarc.com
HOSTER_WWW_ROOT = /var/www/html/cfsitedrafts

The ssh/scp depends on an SSH keypair generated in bitbucket for the repository’s piplines. After generating the keypair, we have placed the public key on the host server in the named user’s ~/.ssh/authorized_keys file and added the host’s fingerprint to the known_hosts section of the SSH keys configuration. You can review this at the “SSH Keys” section of the bitbucket pipeline settings.

Production Build Pipeline

The production build pipeline, which will execute when the master branch is updated, is the same but uses different variable definitions as defined under the “Deployments” section of the pipelines settings. This uses a different bucket archive location, and different hosting server settings.

Was this page useful?   or