cloudogu / reveal.js-docker-example

Advanced example for using web-based slides/presentations via cloudogu/reveal.js-docker

reveal.js-docker-example

Advanced example of cloudogu/reveal.js-docker, providing easy to use, opinionated reveal.js web apps - web-based slides/presentations.

Evolution of cloudogu/continuous-delivery-slides.

Provides

• example slides in markdown, showcasing the features (see rendered version),
• scripts linux / windows to start slide Development mode (changes on the slides lead to automatic reloads in the browser):
  • Start with
    • Linux: ./startPresentation.sh
    • Windows: Right Click on startPresentation.ps1 then Run with PowerShell.
  • Presentation is served at http://localhost:8000
  • This fails if either one of the port 8000 or 35729 is already blocked.
  • You can stop the presentation container by finding the CONTAINER_ID using docker ps, then docker rm -f <CONTAINER_ID.
  • Linux users can avoid port conflicts (e.g. with multiple presentations running) by using
    ./startPresentation.sh internal
    which results in no port bindings to localhost. Instead, the internal IP of the docker container is used
• a Dockerfile that creates an image containing a web-server that serves the presentation as a completely static website:
  • Build with docker build -t presentation
  • Run with docker run --rm -p 8080:8080 presentation
  • Presentation is served at http://localhost:8080
  • For demo purposes have a look at the Image built by this repo:
    docker run --rm -p 8080:8080 cloudogu/reveal.js-example
• a script for printing pdf locally
  • You can enable (lossy but effective, compresses by factor 5 to 10 😱) compression using an env var, e.g. like so

  COMPRESS=true ./printPdf.sh

  • If you're optimizing your PDF
    • Start by viewing the PDF web-view, e.g. http://localhost:8000/?print-pdf
    • Still, sometimes there are slight differences to the acutal PDF.
      Here, you might want to use hot reloading, with a PDF-viewer like okular and this command

  ./printPdf.sh | xargs -I{} mv {} my.pdf
  # You could automate PDF generation using https://github.com/Qard/onchange
  onchange "docs/slides/*" -- ./printPdf.sh | xargs -I{} mv {} my.pdf 

• Kubernetes Resources for running the Docker Image on K8s securely
• a maven POM for deploying the presentation as a maven site into a Raw Nexus Repository and finally
• a Jenkins continuous delivery pipeline that showcases how to deploy
  • to Nexus repo,
  • GitHub Pages and
  • Kubernetes.
• The pipeline also creates a PDF export of the slides.

See also our Blog Posts: Docs As Code - Continuous Delivery of Presentations with reveal.js and Jenkins

• Part 1 - Intro and Deployment to GitHub Pages 🇬🇧 | 🇩🇪
• Part 2 - Deployment to Nexus and Kubernetes 🇬🇧 | 🇩🇪

You can view the latest version of the presentation

• as web-based presentation and
• as PDF on the web or on Jenkins

With a git-based wiki such as Smeagol (see Blog Post) you can edit the slides conveniently from the browser. A change there will trigger the the Jenkins pipeline that deploys to

• Sonatype Nexus or
• Kubernetes.

This example also shows how to deploy deploy your GitHub repo to GitHub Pages.

The workflow with a Cloudogu Ecosystem and GitHub are shown bellow.

Cloudogu Ecosystem	GitHub

Customize theme / style

• Import an existing theme, e.g. from reveal.js-docker

  mkdir -p dist/theme 
  wget https://raw.githubusercontent.com/cloudogu/reveal.js-docker/master/dist/theme/cloudogu-black.css --directory-prefix dist/theme

• Make sure to set the ENV THEME_CSS=... line in Dockerfile to the file name of your theme.
• Customize the theme in in your dist repo
• The theme is automatically picked up when running startPresentation.sh and docker build

Jenkins Build

See Jenkinsfile.

• Makes excessive use of the Jenkins shared library ces-build-lib
• Deploys the presentation to
  • GitHub Pages branch of this repo. To do so, username and password credentials cesmarvin need to be defined in Jenkins. A best practice is to create an access token. These credentials must have write access on the GitHub repo.
    See here for the result.
  • Nexus site repo defined in pom.xml.
    • Username and password credentials ces-nexus need to be defined in Jenkins.
    • These credentials must have write access to the maven site in Nexus:
      • nx-repository-view-raw-<RepoName>-add and
      • nx-repository-view-raw-<RepoName>-edit
      • Where RepoName is defined in pom.xml's url and distributionManagement.site.urls (after /repository/)
      • In this example: nx-repository-view-raw-Cloudogu-Docs-add
    • We need a raw Repo called Cloudogu-Docs in Nexus.
  • the Kubernetes cluster identified by the kubeconfig and the Docker registry defined in Jenkinsfile
    • Docker Registry: Requires username and password credentials hub.docker.com-cesmarvin defined in Jenkins.
      In this example the image cloudogu/continuous-delivery-slides is deployed to Docker Hub.
    • Kubernetes: Requires kubeconfig file defined as Jenkins file credential kubeconfig-oss-deployer. An example for creating the kubeconfig (using create-kubeconfig from zlabjp/kubernetes-scripts):

      kubectl create namespace jenkins-ns
      kubectl create serviceaccount jenkins-sa --namespace=jenkins-ns
      kubectl create rolebinding jenkins-ns-admin --clusterrole=admin --namespace=jenkins-ns --serviceaccount=jenkins-ns:jenkins-sa
      ./create-kubeconfig jenkins-sa --namespace=jenkins-ns > kubeconfig

• Needs Docker available on the jenkins worker
• On failure, sends emails to git commiter.