Skip to content
This repository has been archived by the owner on Aug 16, 2019. It is now read-only.

[Draft] Branch based Multi version Approach

Jump to bottom
Lakhan Mandloi edited this page Mar 21, 2018 · 4 revisions

Use Cases

Following are the expectations -

  • Contributors -

    • contribute in Documentation.

  • Docs Team -

    • contribute in docs & marketing landing pages
    • do build promotions
    • PR reviews

Repositories

The Current Docs site building repo will be divided into 2 repos

Docs Repo

This repo contains docs content source code ( .md files) Eg - https://github.com/dev-sunbird/docs. This repo will have multiple branches where each branch will represent a product version. Master branch is the default branch and represent the upcoming / draft version. To release a version one will have to create a version branch from the master branch. Each branch will contain a version.yaml file which will store the information like -

Site Repo

This repo contains site building code (Jekyll and Marketing Landing Pages) Eg - https://github.com/dev-sunbird/dev-sunbird.github.io . Along with Jekyll Code this will contain -

  • Branches.yaml - This yaml file works like a controlling unit of versions. This stores information such as -
  • Some Shell scripts - to make docs repo code ready for Jekyll builds based on information provided in branches.yaml file. Basically fetching those version branches and placing them at right place to make Jekyll builds feasible.

Processes

Processes are same as the current prod has

Edit a page

  1. Contributor Clicks on edit page link
  2. does modifications on github
  3. sends PR
  4. modified pages urls is added in pr comments
  5. Reviewer and Contributor can reviews the output of pr
  6. Reviewer does necessary changes if any issues found or changes requested by reviewer
  7. Pr is merged by Reviewer
  8. builds are promoted by Docs Team

Add a page

  1. Contributor requests for new page by adding issue on github
  2. Docs team creates a new md file at appropriate place and share link to contributor
  3. Contributor contributes content
  4. Sends pr
  5. added pages urls is added in pr comments
  6. Reviewer and contributor can reviews the output of pr
  7. Reviewer does necessary changes if any issues found or changes requested by reviewer
  8. Pr is merged by reviewer
  9. Reviewer or docs team adds link in sidebar if required
  10. Builds are promoted by docs team

Version Creation and Publishing

  1. Docs team works on master branch for upcoming versions. Necessary information is updated in md files and version.yaml file
  2. Once the version is ready, a new branch is created from the master branch.
  3. Version specific details are added in branches.yaml file of site repo
  4. Review site is generated . Site is reviewed
  5. Builds are promoted after reviewing

Build Promotions

  1. Docs team creates a tag with prefix “releases-” on site repo
  2. Release site is created
  3. Release site is reviewed
  4. If release site is good to go on prod then, the CircleCI workflow is approved to deploy on prod
  5. Artifacts from release site is promoted to the prod
  6. If release site was not good to go prod then necessary changes are done in docs or site repo until the release is good to go.

CI / CD

Triggers

This is same as current prod

Docs Repo

  • PR raised - For each pr raised a pr preview site will be created Eg - pr-19.sunbird.org
  • PR merged - If PR is merged it will trigger the review build of site repo and deploy to dev instance dev.sunbird.org

Site Repo

  • Commits - it will trigger the review build and deploy to dev.sunbird.org
  • Release tag - this will create a site Eg - release-1.2.0.sunbird.org for each releases

Build & Deploy Steps

  • Fetch site repo code
  • Run script to fetch docs repo code based on info provided in branches.yaml
  • Process fetched docs repo code to make them feasible for Jekyll builds
  • Build Site
  • Deploy - This will move the build site to the dev server in their respective folders. like
    • For PR the folder will be pr- Eg : pr-21
    • For release the folder will be release tag Eg: release-1.2.5
    • Dev folder will keep updated from the review trigger of site repo.

Development Server

Nginx of development server needs to be configured such that each subdomain request should be served from their respective folders. So subdomain request should be handled such that it looks for the folder if available with the subdomain name in var/www/ directory. If available then point the the directory else redirect to the dev.sunbird.org. This configuration should be wildcard. Eg -

  • pr-19.sunbird.org should point to var/www/pr-19 folder
  • pr-20.sunbird.org should point to var/www/pr-20 folder
  • release-1.4.5.sunbird.org should point to the var/www/release-1.4.5 folder

Some references -

Background of base and relative path issue in AWS S3 Buckets

Problem Statement -

  • dev.com/releases/1/ and dev.com/releases/2/ are two different sites as per the single bucket deployment process.so when one is navigating the dev.com/releases/1 site then all the relative urls should navigate to the dev.com/releases/1 pages only.
  • In usual cases base tag is not defined in the head sections. So the the Page URL itself becomes the base URL for that page.
    • Example 1 - let site.com/docs/architecture/ be a page and css/style.css file makes that page beautiful , so in this case following things will happen -
      • Since base URL of the page is not defined, so the base url will become - site.com/docs/architecture/
      • Since the base URL is site.com/docs/architecture/ and css href is css/style.css the css file will be looked at site.com/docs/architecture/css/style.css rather than at site.com/css/style.css so the page will not render properly. This can be fixed in two ways -
      • Approach 1 - If we append a '/' in the beginning of css href, than the css file will be looked from the root of the server i.e. site.com/css/style.css than it will start rendering properly .
      • Approach 2 - we add base url '/' on all pages so that it starts rendering properly .but it will add an side effect i.e. all relative paths will start from the serve root rather than the page itself so the more or less it has became the absolute path.
  • Example 2 - Now lets consider folder-ed deployment process we follow - Let dev.com/releases/1/ be a site, dev.com/releases/1/docs/architecture/ be a page and 'css/style.css' makes page beautiful , so in this case following things will happen -
    • Since base URL of the page is not defined, so the base url will become - dev.com/releases/1/docs/architecture/
    • Since the base URL is dev.com/releases/1/docs/architecture/ and css href is css/style.css the css file will be looked at dev.com/releases/1/docs/architecture/css/style.css rather than at dev.com/releases/1/css/style.css so the page will not render properly.Now lets try solutions of previous case - -
    • Approach 1 - If we append a '/' in the beginning of css href, than the css file will be looked from the root of the server i.e. dev.com/css/style.css rather than dev.com/releases/1/css/style.css and hence not a solution .
    • Approach 2 - we add base url '/' on all pages.But this will make all pages relative to the server root. hence not a solution.so the css href will become dev.com/css/style.css
    • Approach 3 - we add base url '/releases/1/' as base url so the all url will become relative to dev.com/releases/1/ rather than dev.com this somehow helps in relative path problem but next thing arises is When release 1 is promoted to the prod - rather then rebuilding the site, the generated site of dev.com/releases/1 should move to the prod. i.e. same code should work in both scenarios - when in root or within some folder. But it fails. We can fix it with the help of JS by checking the host and modifying the base url accordingly but the build promotion concept fails as the environment behaviour is changed. Another thing is it becomes even worse when the multi-version docs comes in picture where we expect to add relative path from docs version landing page rather than from the site baseurl.
    • Approach 4 - Deploying in sub-domains this resolves the baseurl problem but the problem is aws s3 sindle bucket doesn't support sub-domains out of the box.

Background for shifting from AWS s3 bucket to proxy server

AWS S3 doesn't support the wildcard sub-domain from the sub-directories.

Possible solution is deploying code to the proxy server which serves the subdomain content from the respective directories. This serving should be wildcard so that it serves any dynamically created folders.

Clone this wiki locally