showcase & api docs: publish to github pages

[dsebastien]

Build & deploy the showcase and api docs to github pages when creating releases

Preparation:

• enable gh-pages for stark
• create a gh-pages branch
• clean the gh-pages branch (should start empty)
• create the api-docs and showcase folders in that branch
• create the api-docs\stark-core\latest and api-docs\stark-ui\latest folders
• create a latest folder in showcase
• create the showcase app based on starter: showcase: create package #353
• adapt the .travis.yml to also generate the prod build of the showcase
  • added a new script: npm run build:showcase

Then create a script (gh-deploy.sh) executed as part of the Travis CI build that will...

First perform checks:

• checks if the build occurs on the main Stark repository and not on a fork); IF NOT then it exits (0)
• checks if the build occurs on the correct node version (we don't want to publish docs for each version of node we test against); IF NOT then it exits (0)
• checks if the build occurs for a PR; IF SO, then it exits (0)
• checks if the build is for a release; IF NOT then it exits (0)
• checks that the necessary decryption keys for the SSH private key are available as environment variables (necessary to be able to push our changes to GitHub!)

Then generate the API docs

• npm run docs:all

The prepare the docs for upload to the github-pages branch:

• identifies the version the build is executed for
• ensures that the identified version matches the version in stark/showcase/package.json; IF NOT then if fails (-1) because it means that the showcase hasn't been updated for the release
• creates the showcase/<version> folder
• copies the showcase build output to showcase/<version>
• copies the showcase build output to showcase/latest

In addition, for each stark module:

• creates the api-docs/<stark-module>/<version> folder
• generates the api-docs for the module and copies the output to api-docs/<stark-module>/<version>
• copies the api-docs to api-docs/<stark-module>/latest

Finally:

• adds, commits and pushes the changes to the gh-pages branch to github
• question: how will we mock the back-end with GitHub pages?

Docs:

• document the key generation / configuration
  • see last comments

Bonus

• create a DNS CNAME record to nbb.be (e.g., opensource.nbb.be) and make it point to https://nationalbankbelgium.github.io
  • opensource.nbb.be created
• define the custom domain on Stark's repository
• enable HTTPS for the custom domain (need to wait for the certificate to be ready)
• create a homepage and add a link to Stark docs: opensource.nbb.be/stark/api-docs/showcase/latest`

Refs:

• https://gist.github.com/domenic/ec8b0fc8ab45f39403dd
• https://stackoverflow.com/questions/23277391/how-to-publish-to-github-pages-from-travis-ci
• https://www.npmjs.com/package/angular-cli-ghpages
• https://github.com/angular-schule/angular-cli-ghpages/wiki/FAQ
• enable: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/
• https://github.com/domenic/zones/blob/master/deploy.sh

[dsebastien]

Blocked by #148

[dsebastien]

Alternative option for deployment to gh-pages for simpler projects: https://docs.travis-ci.com/user/deployment/pages/

[dsebastien]

@christophercr just thought about this, but so far we didn't think about the distinction between stark-core and stark-ui api docs.. I guess each needs its own sub-folder under api-docs?

So the structure would be like:

| api-docs
|-- stark-core
|---- <version>
|-- stark-ui
|---- <version>

[dsebastien]

Docs publication currently blocked by #127

[dsebastien]

Showcase publication currently blocked by #353

[christophercr]

@dsebastien indeed, we overlooked that. I agree with the folder structure you propose ;)

[dsebastien]

Okay, proposal adapted!

[dsebastien]

I'll adapt the proposal to match our last discussion:

• we'll generate a repo-specific SSH keypair for Stark: ssh-keygen -t rsa -b 4096 -C "..." and save it as stark-ssh
• we'll associate the public key with Stark: this is called a deploy key on github: https://developer.github.com/v3/guides/managing-deploy-keys/ (Settings > Deploy Keys > Add)
• we'll encrypt the private key with travis cli: travis encrypt-file mysuperprivatekey. Travis will store the necessary decryption material inside the repo config in Travis (protected vars)
• we'll store the encrypted private key in the sources
• we'll decrypt the key in the CI, paying attention not to leak it out :p
• we'll use it to clone/push using ssh

Travis CLI:

• Install Ruby to get the gem cli
• Install Travis CLI with gem install travis
• Login to Travis using GH credentials: travis login --org --github-token foo
  • Successfully logged in as ...

Encrypting the private key: travis encrypt-file ./stark-ssh -r NationalBankBelgium/stark

• generates stark-ssh.enc
• provides command to use in the scripts to decrypt the stark-ssh.enc file: openssl aes-256-cbc -K $encrypted_e546efaa49e5_key -iv $encrypted_e546efaa49e5_iv -in stark-ssh.enc -out ./stark-ssh -d
  • Travis will provide us with those variables

[dsebastien]

GH repos are limited to ~1GB and stark-core's API docs alone is ~25MB, so our initial idea of also keeping API docs for nightly builds will not hold for long.

I'll only allow releases to get their published docs.

[christophercr]

One issue to keep in mind while generating the encrypted key on Windows :s travis-ci/travis-ci#4746