diff --git a/content/blog/writing-workshop-instructions-with-hugo-deploy-openshift.md b/content/blog/writing-workshop-instructions-with-hugo-deploy-openshift.md new file mode 100644 index 0000000..f499784 --- /dev/null +++ b/content/blog/writing-workshop-instructions-with-hugo-deploy-openshift.md @@ -0,0 +1,190 @@ +--- +title: "Writing workshop instructions with Hugo and deploying in OpenShift" +date: 2019-02-27T00:00:00+02:00 +opensource: +- Hugo +- OpenShift +--- + +This is the third part of my series covering how to +[Write workshop instructions with Hugo](../writing-workshop-instructions-with-hugo/). In this article, we will deploy our [Hugo mini-training](https://github.com/nmasse-itix/hugo-workshop/) as a container in OpenShift. + +Since Hugo is a static website generator, we only need a web server in our container to serve those pages. Let's settle for nginx that is [neatly packaged as a container image, as part of the Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-nginx114/). + +And to build our final container image that will contain both our website (the static pages to serve) and the web server itself, we will use the [Source-to-image (S2I)](https://github.com/openshift/source-to-image) tool. Hopefully, the nginx image of the Software Collections is already S2I enabled! + +## Install the Source-to-Image tool + +The S2I tool comes as package for Fedora or RHEL distributions, named `source-to-image`. On RHEL, you will have to enable the `rhel-server-rhscl-7-rpms` channel before. + +On a RHEL system, use: + +```sh +sudo yum-config-manager --enable rhel-server-rhscl-7-rpms +sudo yum install source-to-image +``` + +On a Fedora system, use: + +```sh +sudo dnf install source-to-image +``` + +On MacOS, use: + +```sh +brew install source-to-image +``` + +You can confirm the S2I tool is installed by running: + +```raw +$ s2i version +s2i v1.1.6 +``` + +## Pull the nginx container image + +If you are a Red Hat customer, you should be able to use the Red Hat official images: + +```sh +docker pull registry.access.redhat.com/rhscl/nginx-114-rhel7:latest +``` + +Or if you prefer, you can use the image provided by the community: + +```sh +docker pull centos/nginx-114-centos7:latest +``` + +## Customize the S2I assemble script + +The off-the-shelf nginx container image comes with standard S2I scripts that takes a GIT repository of static files and publish them *as-is*. We need to customize those scripts to call Hugo to generates the static files and replace the content of the GIT repository with those static files. + +Hopefully, S2I comes with a nice mechanism to override the standard scripts. We only need to place our scripts in a `.s2i/bin/` directory in our GIT repository. There are two standard scripts: `assemble` (to build the container image) and `run` to start the process from the container image. We will override the `assemble` script. + +Create a `.s2i/bin/assemble` file in your GIT repository with the following content: + +```sh +#!/bin/bash + +# Exit on any error +set -e + +hugo_version=${HUGO_VERSION:-0.54.0} +hugo_bin_name=${HUGO_BIN_NAME:-hugo_${hugo_version}_Linux-64bit.tar.gz} +hugo_bin_url=${HUGO_BIN_URL:-https://github.com/gohugoio/hugo/releases/download/v${hugo_version}/${hugo_bin_name}} + +# Download Hugo +curl -s -o "/tmp/${hugo_bin_name}" -L "${hugo_bin_url}" + +# Install Hugo +tar -C /tmp -xf "/tmp/${hugo_bin_name}" hugo + +# Build the website +mv /tmp/src/ /tmp/git +/tmp/hugo -s /tmp/git +ln -s /tmp/git/public /tmp/src + +# Call the default S2I assemble script +exec /usr/libexec/s2i/assemble +``` + +Make it executable: + +```sh +chmod 755 .s2i/bin/assemble +``` + +Check that your customized `assemble` script is working by running the `s2i build` command: + +```sh +s2i build -c . centos/nginx-114-centos7:latest hugo-mini-training +``` + +The `-c` switch is mandatory here to use our local copy of the GIT repository since it contains changes not yet committed. +If you want the Red Hat official image, adjust the `s2i build` command to replace `centos/nginx-114-centos7:latest` with `registry.access.redhat.com/rhscl/nginx-114-rhel7:latest`. + +You should see the typical Hugo output as part of the build logs: + +```raw +Building sites … +| EN ++------------------+----+ +Pages | 22 +Paginator pages | 0 +Non-page files | 0 +Static files | 77 +Processed images | 0 +Aliases | 0 +Sitemaps | 1 +Cleaned | 0 + +Total in 36 ms +---> Installing application source +---> Copying nginx start-hook scripts... +Build completed successfully +``` + +Commit and push your changes: + +```sh +git add .s2i/bin/assemble +git commit -m 'add s2i support' +git push +``` + +## Deploy on OpenShift + +Once your repository contains the customized S2I script, you can deploy your website on OpenShift using the standard S2I mechanisms. + +```sh +oc new-app centos/nginx-114-centos7:latest~https://github.com/nmasse-itix/hugo-workshop.git --name=hugo-workshop +``` + +If you want the Red Hat official image, adjust the previous command to replace `centos/nginx-114-centos7:latest` with `registry.access.redhat.com/rhscl/nginx-114-rhel7:latest`. Also, do not forget to change the URL to point to your GIT repository instead! + +By default, the custom `assemble` script will build your website with Hugo 0.54.0 (latest version when this post was written) but you can use the version of your choice by setting the `HUGO_VERSION` accordingly. + +For instance, you can downgrade to Hugo 0.53 with: + +```sh +oc set env bc/hugo-workshop HUGO_VERSION=0.53 +``` + +## Continous Deployment + +Part of the hype around Hugo is due to the level of automation you can achieve and especially Continous Deployment. This means the writer pushes his changes to a GIT repository and the website is rebuilt and deployed immediately, in an automated manner. The good news is that you can achieve this very easily with OpenShift! + +First, get the GitHub Webhook URL of your BuildConfig: + +- Connect to your OpenShift Web Console +- Go to **Builds** > **Builds** +- Click on your BuildConfig (`hugo-workshop` in the example) +- Open the **Configuration** tab +- Copy the **GitHub Webhook URL** + +![The BuildConfig on OpenShift](openshift-buildconfig-webhook.png) + +Then, go on your GitHub repository and add a webhook: + +- Go to **Settings** > **Webhooks** +- Click **Add webhook** + +![Add a webhook on GitHub](github-add-webhook.png) + +- Paste your Webhook URL in the **Payload URL** field +- Select `application/json` in the **Content type** dropdown list +- Check **Disable** in the **SSL verification** section if your OpenShift console has a self-signed certificate +- Click **Add webhook** + +![The GitHub webhook](github-webhook.png) + +Try to push some changes to your GitHub repository and see OpenShift rebuilding and deploying your website! + +![OpenShift rebuilding and redeploying your website](openshift-rebuild.png) + +## Conclusion + +In this article we presented a way to deploy a Hugo website as a container in OpenShift and achieve Continuous Deployment. +Stay tuned for the next part of this serie! diff --git a/content/blog/writing-workshop-instructions-with-hugo-variables.md b/content/blog/writing-workshop-instructions-with-hugo-variables.md index dea3bf1..13972e0 100644 --- a/content/blog/writing-workshop-instructions-with-hugo-variables.md +++ b/content/blog/writing-workshop-instructions-with-hugo-variables.md @@ -6,7 +6,7 @@ opensource: --- This is the second part of my series covering how to -[Write workshop instructions with Hugo"](../writing-workshop-instructions-with-hugo/). +[Write workshop instructions with Hugo](../writing-workshop-instructions-with-hugo/). In the first part, we saw how to: - bootstrap a website with Hugo @@ -59,4 +59,4 @@ Congratulation, you can now change your `github_username` and `github_repository` variables at will and see your changes reflect in your pages! -Stay tuned for the next part of this serie! +Be sure to read [part 3: Writing workshop instructions with Hugo and deploying in OpenShift](../writing-workshop-instructions-with-hugo-deploy-openshift/) to learn how to deploy Hugo websites in a container! \ No newline at end of file diff --git a/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/github-add-webhook.png b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/github-add-webhook.png new file mode 100644 index 0000000..d81bc72 Binary files /dev/null and b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/github-add-webhook.png differ diff --git a/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/github-webhook.png b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/github-webhook.png new file mode 100644 index 0000000..bd4196f Binary files /dev/null and b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/github-webhook.png differ diff --git a/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/openshift-buildconfig-webhook.png b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/openshift-buildconfig-webhook.png new file mode 100644 index 0000000..f2a84b0 Binary files /dev/null and b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/openshift-buildconfig-webhook.png differ diff --git a/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/openshift-rebuild.png b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/openshift-rebuild.png new file mode 100644 index 0000000..5998498 Binary files /dev/null and b/static/blog/writing-workshop-instructions-with-hugo-deploy-openshift/openshift-rebuild.png differ