Skip to content

deployingTheSite.md

Latest commit

 

History

History
548 lines (388 loc) · 25.2 KB

deployingTheSite.md

File metadata and controls

548 lines (388 loc) · 25.2 KB

{% set title = "Deploying the Site" %} {% set filename = "deployingTheSite" %} {{ title }}

title: "User Guide: {{ title }}" layout: userGuide.md pageNav: default [_User Guide → {{ title }}_]({{ filename }}.html)

{{ title }}

A site generated by MarkBind can be deployed by simply uploading the generated files to any Web server. In addition, MarkBind provides several convenient deployment options.

Generic steps for deploying a MarkBind site

  1. Set the baseUrl property of the site.json file to match the deploy location.
  2. (Optional) Use the markbind serve command to stage the site locally and confirm the contents are as expected.
  3. Use the markbind build command to generate the site from source files. That command puts the generated site files in a directory named _site (you can change the output directory using parameters supplied to the command).
  4. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.

Steps for deploying multiple MarkBind sites:

  1. Create multiple site.json files. Ensure that the baseUrl property of each site.json file matches its deploy location.
  2. (Optional) Use the markbind serve -s <file> command to stage each site locally and confirm the contents are as expected.
  3. For each site:
    1. Use the markbind build -s <file> command to generate the site from source files.
    2. Upload the site files to the Web server. The sections below explain how to automate this step if you are deploying to some online platforms.

Deploying to GitHub Pages

MarkBind can easily deploy a site to GitHub pages if the project root directory is also a GitHub repo.

Using the markbind deploy command

Running the markbind deploy command will deploy the most recent build of your site to the gh-pages branch of the repo origin and will be available.

Then, navigate to the Settings > Pages section on GitHub for that repository and set the source to the root of the gh-pages branch. You can read this source on GitHub Pages for more details.

Your site will be online at http://<username|org>.github.io/<repo> (e.g., http://se-edu.github.io/se-book).

If you are deploying the site to GitHub pages, the baseUrl setting in the site.json should be set to the "/<repositoryName>" for the links in the deployed site to work correctly.

{{ icon_example }} If you are using GitHub Pages to host your deployed website at repo myorg/myproduct (i.e., the website is published at https://myorg.github.io/myproduct), then your baseUrl should be "/myproduct".

You can override the default deployment settings %%(e.g., repo/branch to deploy)%% in the site.json's deploy section:


markbind deploy does not generate the static site from your source; it simply deploys the files that are already in the _site directory. You need to run markbind build first if you want to generate the site before deploying.

Using CI Platforms

You can setup CI Platforms to automatically build and deploy your site on GitHub Pages every time your GitHub repo is updated.

With the exception of GitHub Actions, a GitHub Personal Access Token with repo permissions is required for deploying your MarkBind site to GitHub Pages via CI tools.

You may refer to GitHub's documentation on how to generate a GitHub Personal Access Token. Ensure that you have enabled repo permissions as shown from the screenshot below.

Take note of the generated token - you will not be able to see it again once you navigate away from the page.

To instruct GitHub Actions to build and deploy the site when you push to the repository, add a GitHub Actions workflow file in your project repo at the location <PROJECT_ROOT>/.github/workflows/deploy.yml A sample workflow file is provided below:

name: Deploy MarkBind Site
on:
  push:
    branches: master

jobs:
  build:
    runs-on: ubuntu-latest
    name: test
    env:
      GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm i -g markbind-cli
      - run: markbind build
      - run: markbind deploy --ci

The sample deploy.yml workflow above uses the default GitHub Token secret that is generated automatically for each GitHub Actions workflow. You may also use a GitHub Personal Access Token in place of the default GitHub Token.

Once you have created the file, commit and push the file to your repo. GitHub Actions should start to build and deploy your MarkBind site. You can verify this by visiting www.github.com/<org|username>/<repo>/actions.

MarkBind provides a helper GitHub Action that you can use to simplify your workflow file. A sample workflow file utilizing the action is as follows:

name: Deploy MarkBind Site
on:
  push:
    branches: master

jobs: 
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Build & Deploy MarkBind site
        uses: MarkBind/markbind-action@v2
        with:
          token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}

Read the action documentation to understand the various configuration options.

For more information on customizing your workflow file to fit your specific needs, you may refer to the GitHub Action Docs.

Adding your repository to Travis CI

Since May 2018, Travis CI has been undergoing migration to travis-ci.com, which changes the way you setup repositories on Travis CI.

  • If you are new to Travis CI, you should add your repository on travis-ci.com.
  • Alternatively, if you are already using Travis CI on travis-ci.org, you can continue to add your repository on travis-ci.org.

  1. Sign in to Travis using your GitHub account.
  2. Accept the authorisation for Travis CI when you are redirected to GitHub.
  3. Go to the Repositories page, and click on the green Activate button.
    %%{{ icon_info }} If you are already using Travis CI, click on the white Manage Repositories on GitHub button instead.%%
  4. Select the repository with the MarkBind site, and add the Travis CI GitHub App to the repository by clicking the green Approve and Install button.
  1. Sign in to Travis using your GitHub account.
  2. Accept the authorisation for Travis CI when you are redirected to GitHub.
  3. Go to the Repositories page.
  4. Find the repository with the MarkBind site.
    %%{{ icon_info }} If the organization/repository is not shown in the list, click on Review and add link at the bottom of the list of organization and follow the steps to give Travis access to the organization containing your repo. After that, come back to the Repositories page and use the Sync Account button to sync your Travis account with GitHub.%%
  5. Activate the repo using the slider switch in front of it.

Configuring your repository in Travis CI

  1. Add an environment variable in Travis CI named GITHUB_TOKEN, with the value set to your generated GitHub Personal Access Token. ==Ensure that Display value in the build log is set to Off.==

  2. Add a .travis.yml file to instruct Travis CI to build and deploy the site when you push to the repository. An example .travis.yml file that can accomplish this is given below:

    language: node_js
node_js:
  - 10
install:
  - npm i -g markbind-cli
script: markbind build
deploy:
  provider: script
  script: markbind deploy --ci
  skip_cleanup: true
  on:
    branch: master

More information about .travis.yml can be found in the Travis CI documentation.

  1. Commit .travis.yml to your MarkBind repository and push the changes. Travis CI should begin to build your site.
  2. Select the MarkBind repository on Travis CI and check the build status to see if it is successful.
  3. Once the build succeeds, your MarkBind site should be online at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book. Travis CI will automatically build and deploy changes to your site as you push new changes to the repository after a few seconds.
    %%{{ icon_info }} You might have to go to the Settings of your repo and configure it to publish GitHub Pages from the gh-pages branch as MarkBind deploys to that branch by default.%%

Configuring Travis CI to only deploy from a specific repository

When Travis CI is set up as explained above, Travis CI will attempt to deploy the site from any repository it is in, including forks. If you want Travis CI to only deploy from a specific repository (eg. only from your main site repository), you can add to the deploy phase a repo condition in the form owner_name/repo_name.

For example, if you only want Travis CI to deploy the site when it is run from the se-edu/se-book repository, the following repo condition should be added to .travis.yml.

  on:
    branch: master
    repo: se-edu/se-book

The repo value can be changed to your specific repository as desired.

Adding your repository to AppVeyor CI

  1. Sign in to AppVeyor CI using your GitHub Account.

  2. Authorize AppVeyor App as GitHub App in the account settings by clicking on the Install AppVeyor App button.

  3. In the projects directory, click on the New Project button.

  4. Finally, select the repository containing your MarkBind site.

Configuring your repository in AppVeyor CI

  1. Ensure that you have generated a GitHub Personal Access token with repo permissions.

  2. Navigate to the project settings page of your repository in AppVeyor CI.

  3. On the left menu, click on Environment.

  4. Under the heading Environment variables, add a custom environment variable named GITHUB_TOKEN, with the value set to the personal access token that was generated in the first step. ==Ensure that you toggle variable encryption by clicking on the padlock.==

  5. Remember to click Save at the bottom of the page.

  6. Add a appveyor.ymlfile at the root of your MarkBind site's repository to instruct AppVeyor CI to build and deploy the site to GitHub Pages when you push to your repository. More information on customizing appveyor.yml can be found in AppVeyor documentation. An example appveyor.yml file is given below:

    environment:
  nodejs_version: '10'

branches:
  only:
    - master

install:
  - ps: Install-Product node $env:nodejs_version
  - npm i -g markbind-cli
  - markbind build
  - markbind deploy --ci

test: off

build: off

Commit and push appveyor.yml to your GitHub repository. Thereafter, AppVeyor CI should begin to run the build script. You are able to view the current build status by clicking on your repository in the AppVeyor projects page. Once the build succeeds, you should be able to view your MarkBind site, after a few seconds, at http://<username|org>.github.io/<repo> e.g., http://se-edu.github.io/se-book.

Adding your repository to Circle CI

  1. Ensure that you have generated a GitHub Personal Access Token with repo permissions.

  2. Sign in to Circle CI using your GitHub account.

  3. In the projects dashboard, click on the Set Up Project button beside the repo containing your MarkBind site.

Configuring your repository in Circle CI

  1. Once you have set up your project, click on the Project Settings button.

  2. On the left, click on the Environment Variables tab and add a custom Environment Variable, GITHUB_TOKEN, which contains the value of your GitHub Personal Access Token.

  3. Commit and push a config.yml file to the repo containing your MarkBind Site that instructs Circle CI to build and deploy your MarkBind site to GitHub Pages whenever you push to your repository. Ensure that the config.yml file is located in the <PROJECT_ROOT>/.circleci/ directory. A sample config.yml file is shown below:

    jobs:
  Build-And-Deploy:
    docker:
      - image: 'cimg/base:stable'
    steps:
      - checkout
      - node/install:
          node-version: "14"
          npm-version: "7"
          install-yarn: false
      - run: node --version
      - run: npm i -g markbind-cli
      - run: markbind build
      - run: markbind deploy --ci
version: 2.1
orbs:
  node: circleci/node@4.1.0
workflows:
  Deploy-MarkBind-Site:
    jobs:
      - Build-And-Deploy

After you have pushed the config.yml file to your remote repo, you should see Circle CI starting to run the Deploy job in your projects dashboard. Once it is successful, you should be able to view your MarkBind site at http://<username|org>.github.io/<repo>.

For more information on customizing your build script, you may refer to Circle CI Config Reference Document.

Deploying to Netlify

You can setup Netlify to automatically build and deploy your site on their platform every time your GitHub repo is updated.

Here are the steps to set up Netlify:

  1. Go to https://app.netlify.com/ and sign up

  2. Next go to https://app.netlify.com/account/sites and select New site from Git

  3. Select your git provider

  4. Select your MarkBind site repository

  5. Update the build settings as follows and hit Deploy site:

    • Build Command: npm i markbind-cli -g && markbind build --baseUrl
    • Publish directory: _site
    • Show advanced: Add a new variable with the key as NODE_VERSION and the value as {{ node_version_number }} or higher

Now your site will be deployed on Netlify at the given address specified after deployment. It will be updated automatically when the default branch of your repo is updated.

Previewing Pull Requests for MarkBind sites

If you are hosting your MarkBind project on GitHub, you can setup PR previews in order to automatically build and deploy the modified MarkBind site based on the changes in the PR.

Previewing PRs using Netlify

By following the steps to deploy to Netlify in the previous section, you would automatically be able to preview PRs.

You can preview the updated site at the bottom of the pull request by clicking on details link in the PR:

For more information on previewing PRs with Netlify, you may refer to Netlify's docs.

Previewing PRs using Surge

You may also preview PRs using Surge, which is an NPM package that does static web publishing. Here are the steps to do so:

  1. First install Surge using by typing npm install --global surge on your terminal.

  2. Next, type surge in the terminal. You should see the following prompt:

  3. Proceed to create a Surge account. After you have set up your account, you should see the following screen:

  4. Hit CTRL-C on your keyboard to quit the current running Surge process.

    The rest of the Surge setup is unnecessary for the purposes of setting up PR previews. You may still proceed with the rest of the setup such as setting the project directory and the domain name, if you wish to.

  5. Next, type surge token to generate your surge token.

  6. In the repo of your MarkBind site, create a new secret by going to "Settings"->"Secrets" and naming it as SURGE_TOKEN and setting its value to the value of the generated surge token.

    After aquiring the surge token, you may want to utilize the provided MarkBind reusable workflows to conveniently set up your PR preview via Surge.sh.

    If you would like to find out more about how it works behind the scene and how to do it yourself, read on to see the detailed steps that need to be specified in your workflow files.

  7. Commit and push the following 2 files into your MarkBind site repo, in the directory <PROJECT_ROOT>/.github/workflows/.

{% raw %}

name: Receive MarkBind PR

# read-only
# no access to secrets
on:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:        
      - uses: actions/checkout@v2
      - name: Install Node
        uses: actions/setup-node@v2
        with:
          node-version: 14
      - name: Build MarkBind website
        run: |
          npm install -g markbind-cli
          markbind build
      - name: Save PR number and HEAD commit
        if: ${{ success() && github.event_name == 'pull_request' }}
        run: |
          mkdir -p ./pr
          echo ${{ github.event.number }} > ./pr/NUMBER
          echo ${{ github.event.pull_request.head.sha }} > ./pr/SHA
      - name: Upload artifacts 
        if: ${{ success() && github.event_name == 'pull_request' }}
        uses: actions/upload-artifact@v2
        with:
          name: markbind-deployment
          path: |
            ./_site
            ./pr

{% endraw %}

Setting up the PR URL

In line 34 of the workflow code below, you are required to update the PR_URL according to your needs. We recommend just changing the section <YOUR_BASE_URL> to something that can easily identify your MarkBind project repository.

For example, if the name of your repository is MyRepo, and it is managed under an organization MyOrganization, you could replace <YOUR_BASE_URL> to myorganization-myrepo and your PR Preview will be deployed at the following URL: https://pr-<PR_NUMBER>-myorganization-myrepo.surge.sh.

Advanced users may completely replace the default PR_URL. ==It is recommended to test your workflow code on a test repo before using it for your MarkBind project repo.==

{% raw %}

name: Deploy PR Preview

# Runs after PR is received and build by markbind-cli
# Has access to repo secrets
on:
  workflow_run:
    workflows: ["Receive MarkBind PR"]
    types:
      - completed

jobs:
  build:
    runs-on: ubuntu-latest
    name: Deploying to surge
    steps:
      - uses: actions/checkout@v2
      - name: Download built MarkBind site artifacts
        uses: dawidd6/action-download-artifact@v2
        with:
          workflow: receivePR.yml
          run_id: ${{ github.event.workflow_run.id }}
          name: markbind-deployment
          path: .
      - name: Extract PR number
        id: pr-number
        run: echo '::set-output name=ACTIONS_PR_NUMBER::'$(cat ./pr/NUMBER)
      - name: Install Node
        uses: actions/setup-node@v2
        with:
          node-version: 14
      - name: Build PR preview url
        id: pr-url
        run: |
          PR_URL="https://pr-${{ steps.pr-number.outputs.ACTIONS_PR_NUMBER }}-<YOUR_BASE_URL>.surge.sh/"
          echo '::set-output name=ACTIONS_PREVIEW_URL::'$PR_URL
      - name: Install surge and deploy PR to surge
        run: |
          npm i -g surge
          surge --project ./_site --domain ${{ steps.pr-url.outputs.ACTIONS_PREVIEW_URL }}
        env:
          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}
      - name: Find existing PR preview link comment
        uses: peter-evans/find-comment@v1
        id: fc
        with:
          issue-number: ${{ steps.pr-number.outputs.ACTIONS_PR_NUMBER }}
          body-includes: Your PR can be previewed
      - name: Comment PR preview link in PR
        if: ${{ steps.fc.outputs.comment-id == 0 }}
        uses: peter-evans/create-or-update-comment@v1
        with:
          issue-number: ${{ steps.pr-number.outputs.ACTIONS_PR_NUMBER }}
          body: |
            Thank you for submitting the Pull Request! :thumbsup: 

            Your PR can be previewed [here](${{ steps.pr-url.outputs.ACTIONS_PREVIEW_URL }})

{% endraw %}

Finally, you may open a PR to the repo of your MarkBind site. If everything is configured correctly, after a few minutes, you should be able to see a github-actions bot automatically commenting on the PR with a link to preview the updated MarkBind site.

For more information on Surge, you may refer to Surge's docs.

Relevant Tips & Tricks

{% from "njk/common.njk" import previous_next %} {{ previous_next('themes', 'versioning') }}