├── .s2i └── environment ├── .workshop ├── develop-settings.sh ├── settings.sh ├── setup └── build ├── .gitmodules ├── workshop ├── content │ ├── workshop-overview.md │ ├── exercises │ │ ├── 17-workshop-only.md │ │ ├── 10-template-engine.md │ │ ├── 18-workshop-deletion.md │ │ ├── 20-editing-content.md │ │ ├── 11-presenter-slides.md │ │ ├── 13-share-workshops.md │ │ ├── 03-directory-layout.md │ │ ├── 19-local-deployment.md │ │ ├── 14-remote-hosting.md │ │ ├── 09-page-navigation.md │ │ ├── 04-building-image.md │ │ ├── 16-multiple-users.md │ │ ├── 15-deploy-settings.md │ │ ├── 08-embedded-links.md │ │ ├── 02-workshop-scripts.md │ │ ├── 01-sample-workshop.md │ │ ├── 06-page-formatting.md │ │ ├── 12-build-and-setup.md │ │ ├── 05-workshop-config.md │ │ └── 07-data-variables.md │ ├── setup-environment.md │ └── workshop-summary.md ├── workshop.yaml ├── modules.yaml └── slides │ └── index.html ├── Dockerfile ├── README.md └── LICENSE /.s2i/environment: -------------------------------------------------------------------------------- 1 | TERMINAL_TAB=split 2 | -------------------------------------------------------------------------------- /.workshop/develop-settings.sh: -------------------------------------------------------------------------------- 1 | WORKSHOP_IMAGE=quay.io/openshifthomeroom/lab-workshop-content:develop 2 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule ".workshop/scripts"] 2 | path = .workshop/scripts 3 | url = https://github.com/openshift-homeroom/spawner-scripts.git 4 | branch = stable/2.x 5 | -------------------------------------------------------------------------------- /workshop/content/workshop-overview.md: -------------------------------------------------------------------------------- 1 | In this workshop you will learn how to create and structure the content for your own workshop. You will also learn how to deploy your workshop content to be able to test it. 2 | -------------------------------------------------------------------------------- /.workshop/settings.sh: -------------------------------------------------------------------------------- 1 | WORKSHOP_NAME=lab-workshop-content 2 | WORKSHOP_IMAGE=quay.io/openshifthomeroom/lab-workshop-content:1.13 3 | WORKSHOP_MEMORY=512Mi 4 | AUTH_USERNAME=workshop 5 | AUTH_PASSWORD=workshop 6 | SPAWNER_MODE=learning-portal 7 | RESOURCE_BUDGET=medium 8 | MAX_SESSION_AGE=3600 9 | IDLE_TIMEOUT=300 10 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM quay.io/openshifthomeroom/workshop-dashboard:5.0.0 2 | 3 | USER root 4 | 5 | COPY . /tmp/src 6 | 7 | RUN rm -rf /tmp/src/.git* && \ 8 | chown -R 1001 /tmp/src && \ 9 | chgrp -R 0 /tmp/src && \ 10 | chmod -R g+w /tmp/src 11 | 12 | ENV TERMINAL_TAB=split 13 | 14 | USER 1001 15 | 16 | RUN /usr/libexec/s2i/assemble 17 | -------------------------------------------------------------------------------- /.workshop/setup: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # This 'setup' script is where you can add steps that should be run each 4 | # time the container for the workshop is started. Note that if you are 5 | # using persistent storage with a workshop and make changes to files from 6 | # this script, or are deploying applications, your scripts must cope with 7 | # the steps having already been run. This is because this script will be 8 | # run a second time if the container were restarted for some reason. 9 | -------------------------------------------------------------------------------- /.workshop/build: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # This 'build' script is where you can add steps that should be run when 4 | # building the image for your custom workshop. 5 | 6 | # Move the workshop content to '/opt/app-root/workshop'. It could be left 7 | # at it's default location of '/opt/app-root/src/workshop', but by moving it, 8 | # it is out of view of the user doing the workshop and they aren't likely to 9 | # delete it by accident and break the display of the workshop content. 10 | 11 | mv workshop /opt/app-root/workshop 12 | 13 | # Also delete some of the other files from the top of the Git repository we 14 | # don't need for running the workshop. 15 | 16 | rm -f Dockerfile README.md LICENSE 17 | 18 | # If the workshop requires Git, it is necessary to set some defaults for 19 | # the name and email of the user for Git. 20 | 21 | git config --global user.email "you@example.com" 22 | git config --global user.name "Your Name" 23 | -------------------------------------------------------------------------------- /workshop/workshop.yaml: -------------------------------------------------------------------------------- 1 | name: Workshop Content 2 | 3 | modules: 4 | activate: 5 | - workshop-overview 6 | - setup-environment 7 | - exercises/01-sample-workshop 8 | - exercises/02-workshop-scripts 9 | - exercises/03-directory-layout 10 | - exercises/04-building-image 11 | - exercises/05-workshop-config 12 | - exercises/06-page-formatting 13 | - exercises/07-data-variables 14 | - exercises/08-embedded-links 15 | - exercises/09-page-navigation 16 | - exercises/10-template-engine 17 | - exercises/11-presenter-slides 18 | - exercises/12-build-and-setup 19 | - exercises/13-share-workshops 20 | - exercises/14-remote-hosting 21 | - exercises/15-deploy-settings 22 | - exercises/16-multiple-users 23 | - exercises/17-workshop-only 24 | - exercises/18-workshop-deletion 25 | - exercises/19-local-deployment 26 | - exercises/20-editing-content 27 | - workshop-summary 28 | -------------------------------------------------------------------------------- /workshop/content/exercises/17-workshop-only.md: -------------------------------------------------------------------------------- 1 | The aim for a workshop is to provide an interactive environment where users will run the steps covered by the workshop content in their own session. 2 | 3 | If you need to host online a permanently available copy of the workshop content, but without the interactive environment, you can use the `deploy-personal.sh` script, but override the `DASHBOARD_MODE` settings with the value `workshop-only`. 4 | 5 | ``` 6 | .workshop/scripts/deploy-personal.sh --override DASHBOARD_MODE=workshop-only 7 | ``` 8 | 9 | The workshop content will be displayed full screen, without the dashboard, or any access to the terminal, embedded web console, or slides. 10 | 11 | Where the workshop content marks code blocks as executable, when in full screen mode, they will be shown instead as blocks which when clicked, will be copied to the browser paste buffer. 12 | 13 | If desired, you can create a separate settings file with this setting, and use the `--settings` option to refer to it. 14 | -------------------------------------------------------------------------------- /workshop/content/exercises/10-template-engine.md: -------------------------------------------------------------------------------- 1 | All content in a page will be displayed. If you need to have content which should only be displayed if certain data variables are set, or need to be able to use some other type of conditional logic, you can optionally enable use of the [Liquid](https://www.npmjs.com/package/liquidjs) template engine. 2 | 3 | To enable this, add the `config.template_engine` field to the modules configuration file. 4 | 5 | ``` 6 | config: 7 | template_engine: liquid.js 8 | ``` 9 | 10 | This will allow you to use the syntax implemented by the Liquid template engine. 11 | 12 | ``` 13 | {% if LANGUAGE == 'java' } 14 | .... 15 | {% endif %} 16 | {% if LANGUAGE == 'python' } 17 | .... 18 | {% endif %} 19 | ``` 20 | 21 | Note that when enabling the template engine, the way you make use of data variables changes. 22 | 23 | Instead of use the `%` character to enclose the name of the data variable you want inserted, you need to use the Liquid convention for referencing data variables. That is, `{{ LANGUAGE }}`. 24 | -------------------------------------------------------------------------------- /workshop/content/setup-environment.md: -------------------------------------------------------------------------------- 1 | Before starting the workshop, check that you are logged in correctly and will be able to deploy applications. To do this run: 2 | 3 | ```execute 4 | oc auth can-i create pods 5 | ``` 6 | 7 | Did you type the command in yourself? If you did, click on the command instead and you will find that it is executed for you. You can click on any command which has the icon shown to the right of it, and it will be copied to the interactive terminal and run. If you would rather make a copy of the command so you can paste it to another window, hold down the shift key when you click on the command. 8 | 9 | If the output from the `oc auth can-i` command is `yes`, you are all good to go, and you can scroll to the bottom of the page and click on "Start Workshop". 10 | 11 | If instead of the output `yes`, you see: 12 | 13 | ``` 14 | no - no RBAC policy matched 15 | ``` 16 | 17 | or any other errors, then the environment is not deployed correctly. Check the [GitHub repository](https://github.com/openshift-homeroom/lab-workshop-content) for this workshop for details of how to deploy it. 18 | -------------------------------------------------------------------------------- /workshop/content/workshop-summary.md: -------------------------------------------------------------------------------- 1 | This is the end of the workshop. 2 | 3 | Check the `README` file for this workshop for instructions on how to delete it, if you had deployed it yourself. 4 | 5 | This workshop content can be found at: 6 | 7 | * https://github.com/openshift-homeroom/lab-workshop-content 8 | 9 | The Git repositories which you can use as a starting point for your own workshops can be found at: 10 | 11 | * https://github.com/openshift-homeroom/lab-markdown-sample 12 | * https://github.com/openshift-homeroom/lab-asciidoc-sample 13 | 14 | The workshop scripts used to deploy workshops which you include with your workshop as a Git submodule, can be found at: 15 | 16 | * https://github.com/openshift-homeroom/workshop-scripts 17 | 18 | Workshop content is used to create a custom image deriving from the workshop dashboard image found at: 19 | 20 | * https://github.com/openshift-homeroom/workshop-dashboard 21 | 22 | That Git repository also contains the templates used by `deploy-personal.sh`, for deploying a single workshop. 23 | 24 | For multiple users, the workshop spawner and the templates used by `deploy-spawner.sh`, can be found at: 25 | 26 | * https://github.com/openshift-homeroom/workshop-spawner 27 | -------------------------------------------------------------------------------- /workshop/content/exercises/18-workshop-deletion.md: -------------------------------------------------------------------------------- 1 | When done with a workshop and you want to delete everything, if it is a personal workshop deployment, you can run: 2 | 3 | ```execute 4 | .workshop/scripts/delete-personal.sh 5 | ``` 6 | 7 | Do this now and it will clean up your deployment of the sample workshop content. 8 | 9 | Because you built the workshop image from local files in the Git repository, you should also run: 10 | 11 | ```execute 12 | .workshop/scripts/delete-workshop.sh 13 | ``` 14 | 15 | This will delete the build configuration and image streams for the workshop. 16 | 17 | If you used the workshop spawner, you would instead run: 18 | 19 | ``` 20 | .workshop/scripts/delete-spawner.sh 21 | ``` 22 | 23 | and if you built the workshop from local files when using the workshop spawner, once again run: 24 | 25 | ``` 26 | .workshop/scripts/delete-workshop.sh 27 | ``` 28 | 29 | In the case of using the workshop spawner, if the workshop had been setup to deploy special global resources in the cluster, you may also need to run: 30 | 31 | ``` 32 | .workshop/scripts/delete-resources.sh 33 | ``` 34 | 35 | You should refer to the description of a specific workshop to determine if that is necessary, or when you should run it. 36 | -------------------------------------------------------------------------------- /workshop/content/exercises/20-editing-content.md: -------------------------------------------------------------------------------- 1 | Now that you have gone through this workshop, you can download the sample workshop you want to use as a starting point for your own workshop. Delete the pages under the `workshop/content/exercises` directory in your copy, add your own pages, and update the workshop and modules configuration files, as well as the deployment settings file. 2 | 3 | When editing your workshop content on your local computer, you can use editors such as Atom and VSCode. Because images are placed in the same directory as the markdown files, preview modes of these editors will work, including the embedded images, and you can see what your content should look like without needing to first deploy it. 4 | 5 | It is recommended you use such editors with a preview mode, as it means you can make a whole batch of changes and see what it looks like before needing to build a new image containing the content and deploy it, to test any steps. 6 | 7 | Do be aware that these editors no not know anything about the annotations added to code blocks, so you will not get any visual indicators of where you have applied them. Data variables will also not be expanded, nor any template logic if the template engine is enabled. It is possible that template logic may interfere with any live preview feature of the editors. 8 | -------------------------------------------------------------------------------- /workshop/content/exercises/11-presenter-slides.md: -------------------------------------------------------------------------------- 1 | If a workshop includes a presentation, slides can be included by placing them in the `workshop/slides` directory. Anything in this directory will be served up as static files via a HTTP web server. The default web page should be provided as `index.html`. 2 | 3 | To support the use of [reveal.js](https://revealjs.com/), static media assets for that package are already bundled and available at the standard URL paths that the package expects. You should therefore be able to drop your slide presentation using reveal.js into the `workshop/slides` directory and it will work with no additional setup. 4 | 5 | For slides bundled as a PDF file, add the PDF file to `workshop/slides` and then add an `index.html` which displays the PDF [embedded](https://stackoverflow.com/questions/291813/recommended-way-to-embed-pdf-in-html) in the page. 6 | 7 | You can reference the slides from workshop content using %slides_url% as target of a link. 8 | 9 | * [Slides](%slides_url%) - %slides_url% 10 | 11 | If you are using reveal.js for the slides and you have history enabled, or are using section IDs to support named links, you can use an anchor to a specific slide and that specific slide will be opened. 12 | 13 | * [Questions](%slides_url%#/questions) - %slides_url%#/questions 14 | 15 | In both cases, when using embedded links to the slides in workshop content, if the workshop content is displayed as part of the dashboard, the slides will be opened in the tab to the right rather than as a separate browser window or tab. 16 | -------------------------------------------------------------------------------- /workshop/content/exercises/13-share-workshops.md: -------------------------------------------------------------------------------- 1 | Workshops are shared by building the content, and any additional files or software, into a container image. The container image would then be hosted on an image registry such as Quay.io or Docker Hub. 2 | 3 | In this workshop, the container image for the workshop was built in OpenShift using a `docker` type build. You could also use the `docker` or `buildah` command line tools to build it on your own local computer and push the resulting image up to an image registry. 4 | 5 | Services such as Quay.io, which provide the means to build container images from a hosted Git repository could also be used 6 | 7 | If there is no requirement to be able to add steps to the `Dockerfile` which run as the `root` user, the `s2i` command line tool could also be used by using the `workshop-dashboard` base image as an S2I builder image. 8 | 9 | If you have built your workshop into an image and are hosting it on an image registry that would be accessible to whoever wants to run the workshop, you can update the `.workshop/settings.sh` file with its location. 10 | 11 | ```execute 12 | cat .workshop/settings.sh 13 | ``` 14 | 15 | Change the `WORKSHOP_IMAGE` variable to be the name that identifies where your image is being made available. 16 | 17 | When this is defined and part of your Git repository, when the `deploy-personal.sh` script is run to deploy the workshop, it will pull down and use your image. There will be no need to run `build-workshop.sh` to build the image for the workshop from the local source files from the Git repository. 18 | 19 | To ensure that a specific version of the workshop is being used, rather than the latest version which may be in a state of development, you can when setting `WORKSHOP_IMAGE` reference a specific version tag. 20 | -------------------------------------------------------------------------------- /workshop/content/exercises/03-directory-layout.md: -------------------------------------------------------------------------------- 1 | From the output of initially running `git commit` with the sample workshop content, you will have seen a number of files located in the top level directory, and a number of sub directories forming a hierarchy. 2 | 3 | The files in the top level directory are: 4 | 5 | * `README.md` - A file telling everyone what the workshop in your Git repository is about, and how to deploy it. Replace the current content provided in the sample workshop with your own. 6 | * `LICENSE` - A license file so people are clear about how they can use your workshop content. Replace this with what license you want to apply to your workshop content. 7 | * `Dockerfile` - The steps to build your workshop into an image ready for deployment. This would be left as is, unless you want to customize it to install additional system packages. 8 | 9 | Key sub directories and the files contained within them are: 10 | 11 | * `workshop` - Directory under which your workshop files reside. 12 | * `workshop/modules.yaml` - Configuration file with details of available modules which make up your workshop, and data variables for use in content. 13 | * `workshop/workshop.yaml` - Configuration file which provides the name of the workshop, the list of active modules for the workshop, and any overrides for data variables. 14 | * `workshop/content` - Directory under which your workshop content resides, including images to be displayed in the content. 15 | * `.workshop/build` - A script in which you can specify steps to be run when the image for your workshop is built. 16 | * `.workshop/setup` - A script in which you can specify steps to be run each time the container your workshop is deployed into starts. 17 | * `.workshop/settings.sh` - A settings file which describes attributes of the workshop, for when using the workshop scripts to deploy the workshop. 18 | -------------------------------------------------------------------------------- /workshop/modules.yaml: -------------------------------------------------------------------------------- 1 | config: 2 | vars: 3 | - name: OC_VERSION 4 | value: undefined 5 | - name: KUBECTL_VERSION 6 | value: undefined 7 | 8 | modules: 9 | workshop-overview: 10 | name: Workshop Overview 11 | exit_sign: Setup Environment 12 | setup-environment: 13 | name: Workshop Setup 14 | exit_sign: Start Workshop 15 | exercises/01-sample-workshop: 16 | name: Sample Workshop 17 | exercises/02-workshop-scripts: 18 | name: Workshop Scripts 19 | exercises/03-directory-layout: 20 | name: Directory Layout 21 | exercises/04-building-image: 22 | name: Building Image 23 | exercises/05-workshop-config: 24 | name: Workshop Config 25 | exercises/06-page-formatting: 26 | name: Page Formatting 27 | exercises/07-data-variables: 28 | name: Data Variables 29 | exercises/08-embedded-links: 30 | name: Embedding Links 31 | exercises/09-page-navigation: 32 | name: Page Navigation 33 | exercises/10-template-engine: 34 | name: Template Engine 35 | exercises/11-presenter-slides: 36 | name: Presenter Slides 37 | exercises/12-build-and-setup: 38 | name: Build and Setup 39 | exercises/13-share-workshops: 40 | name: Share Workshops 41 | exercises/14-remote-hosting: 42 | name: Remote Hosting 43 | exercises/15-deploy-settings: 44 | name: Deploy Settings 45 | exercises/16-multiple-users: 46 | name: Multiple Users 47 | exercises/17-workshop-only: 48 | name: Workshop Only 49 | exercises/18-workshop-deletion: 50 | name: Workshop Deletion 51 | exercises/19-local-deployment: 52 | name: Local Deployment 53 | exercises/20-editing-content: 54 | name: Editing Content 55 | workshop-summary: 56 | name: Workshop Summary 57 | exit_sign: Finish Workshop 58 | -------------------------------------------------------------------------------- /workshop/content/exercises/19-local-deployment.md: -------------------------------------------------------------------------------- 1 | In this workshop we built the image for the workshop in OpenShift. You can also use `docker` or `buildah` on your local computer. 2 | 3 | Building the image locally can result in faster turn around times on builds than building it in OpenShift or using separate CI/CD infrastructure. 4 | 5 | Even though the image is being built locally, and is principally designed to be run in OpenShift, you can still run it with your local container run time. In doing this you will not have access to the embedded web console, and you will need to manually login to any remote OpenShift cluster from the terminal before going through the workshop, but everything else should still work. 6 | 7 | To build the workshop image locally using `docker` you would run: 8 | 9 | ``` 10 | docker build -t lab-sample-workshop . 11 | ``` 12 | 13 | To run the image, you would then use: 14 | 15 | ``` 16 | docker run --rm -p 10080:10080 lab-sample-workshop 17 | ``` 18 | 19 | You can then access the workshop environment using `http://localhost:10080`. 20 | 21 | If you want to be able to do iterative changes and test them without needing to rebuild the image each time, you can run: 22 | 23 | ``` 24 | docker run --rm -p 10080:10080 -v `pwd`:/opt/app-root/src lab-sample-workshop 25 | ``` 26 | 27 | This will mount your local Git repository directory into the container and the local files will be used. Each time you change the content of a page, refresh the web browser to view the latest version. You will only need to stop and restart the container if you make changes to the YAML configuration files or the `config.js` file if you are using it. 28 | 29 | If using this method of mounting your local Git repository into the container, if the steps performed in the workshop result in modifications to files under version control, make sure you don't subsequently commit those changes. Instead, you will need to make sure you rollback such changes each time you want to run through the steps in the workshop. 30 | -------------------------------------------------------------------------------- /workshop/slides/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | reveal.js 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 23 | 24 | 25 |
26 |
27 |
28 |
29 |

Workshop Content

30 |
31 |
32 |
33 |

Questions?

34 |
35 |
36 |
37 | 38 | 39 | 40 | 41 | 54 | 55 | 56 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | LAB - Workshop Content 2 | ====================== 3 | 4 | This repository provides a workshop where you will learn how to create and structure the content for your own workshop. You will also learn how to deploy your workshop content to be able to test it. 5 | 6 | To deploy the workshop, first clone a copy of the master branch of this Git repository to your own machine using the command: 7 | 8 | ``` 9 | git clone --single-branch --branch master --recurse-submodules https://github.com/openshift-homeroom/lab-workshop-content.git 10 | ``` 11 | 12 | Change the working directory to `lab-workshop-content`. 13 | 14 | If you forgot to use the `--recurse-submodules` option when cloning the repository, run: 15 | 16 | ``` 17 | git submodule update --init --recursive 18 | ``` 19 | 20 | It is recommended you now create a new project into which to deploy the workshop. The same project will be used by the workshop as it steps you through the different ways workshops can be deployed. When finished, you can delete the whole project to have everything removed. 21 | 22 | ``` 23 | oc new-project workshop 24 | ``` 25 | 26 | Now deploy the workshop by running: 27 | 28 | ``` 29 | .workshop/scripts/deploy-personal.sh 30 | ``` 31 | 32 | The output from the script will show the host name to access from your web browser. You can also see the host name by running: 33 | 34 | ``` 35 | oc get routes lab-workshop-content 36 | ``` 37 | 38 | Access to the workshop environment will be password protected and you will see a browser popup for entering user credentials. The username to enter is `workshop`. The password will also be `workshop`. 39 | 40 | When you are finished you can delete the project you created. 41 | 42 | If you didn't follow the recommendation of using a new project, and instead used an existing project, run: 43 | 44 | ``` 45 | .workshop/scripts/delete-personal.sh 46 | ``` 47 | 48 | Note that this will not delete anything which may have been deployed when you went through the workshop. If you used an existing project, ensure that you go right through the workshop and execute any steps described in it for deleting any deployments it had you make. 49 | -------------------------------------------------------------------------------- /workshop/content/exercises/14-remote-hosting.md: -------------------------------------------------------------------------------- 1 | The recommended approach to distributing a workshop is to create a container image which packages up your workshop. By having everything packaged up as an image, rather than content needing to be downloaded when the workshop is run, it potentially allows for a workshop to be run in disconnected environments. 2 | 3 | If you don't have a requirement for running workshops in a disconnected environment, and instead want to use a hosted Git repository as the source of the workshop content, you can, but you will loose the ability to bundle additional applications or source code files. 4 | 5 | To deploy a workshop from a Git repository, edit the `.workshop/settings.sh` file and remove the entry for `WORKSHOP_IMAGE`. Doing this will mean that the default dashboard base image will be used. At the same time, add a setting for `DOWNLOAD_URL`. 6 | 7 | The `DOWNLOAD_URL` setting should define the HTTP server URL for where the workshop content is hosted. This needs to correspond to the `workshop` directory, not the root of the Git repository. 8 | 9 | If you were using GitHub to host the workshop content, you would use the GitHub URL for raw content. For example: 10 | 11 | ``` 12 | DOWNLOAD_URL=https://raw.githubusercontent.com/openshift-homeroom/lab-markdown-sample/master/workshop 13 | ``` 14 | 15 | When the settings are defined this way, the workshop will be deployed using the default dashboard base image, but when the container starts up, it will download the workshop content from the HTTP server. Which files to download for the workshop content will be determined from the workshop and modules file. 16 | 17 | When this mode is used, you cannot have `build` or `setup` scripts, nor have slides. Any files outside of the workshop directory will also not be available for use during the workshop. 18 | 19 | You can add a `WORKSHOP_FILE` setting in `.workshop/settings.sh` if you need to override which workshop file is used. 20 | 21 | If you need additional command line tools or packages available, you can create a custom dashboard image with those, but without any workshop content added, and refer to that image on an image registry using the `WORKSHOP_IMAGE` setting. It will be used in place of the default dashboard image. 22 | -------------------------------------------------------------------------------- /workshop/content/exercises/09-page-navigation.md: -------------------------------------------------------------------------------- 1 | The purpose of a workshop is to guide users through a set of steps to run, where different sections are maintained as different pages. The order in which pages are traversed, is dictated by the order in which modules are listed under the `modules.activate` field in the workshop configuration file. The order in which modules appear in the modules configuration file is not relevant. 2 | 3 | ``` 4 | name: Markdown Sample 5 | 6 | modules: 7 | activate: 8 | - workshop-overview 9 | - setup-environment 10 | - exercises/01-sample-content 11 | - workshop-summary 12 | ``` 13 | 14 | If you need to run more than one variant of the workshop, you can provide more than one workshop configuration file, each activating a different set of modules, and select which should be used using the `WORKSHOP_FILE` environment variable. 15 | 16 | At the bottom of each page a "Continue" button will be displayed to go to the next page in sequence. The label for this button can be customised if necessary, by setting the `exit_sign` field in the entry for the module in the modules configuration file. 17 | 18 | ``` 19 | modules: 20 | workshop-overview: 21 | name: Workshop Overview 22 | exit_sign: Setup Environment 23 | setup-environment: 24 | name: Setup Environment 25 | exit_sign: Start Workshop 26 | exercises/01-sample-content: 27 | name: Sample Content 28 | workshop-summary: 29 | name: Workshop Summary 30 | exit_sign: Finish Workshop 31 | ``` 32 | 33 | For the last module in the workshop, a button will still be displayed, but where the user is taken when the button is pressed can vary. 34 | 35 | If you want the user to be taken to a different web site upon completion, always leaving the workshop environment in its current state, you can set the `exit_link` field of the final module to the external URL. 36 | 37 | When a workshop session is being created by the workshop spawner, it will inject its own special URL for the exit link via the `RESTART_URL` environment variable. When the user clicks on the final button in this case, the current workshop environment will be shutdown and the user will be redirected back to the start of the workshop, with a new workshop environment being created, or back to a page where they can pick which workshop they want to do next. 38 | 39 | If the `exit_link` field is not defined, nor does a spawner inject a URL to start over, the user will be redirected back to the starting page of the workshop, leaving the current workshop environment intact. 40 | 41 | The recommendation is that for the last page, the `exit_sign` be set to `Finish Workshop` and `exit_link` not be specified. This way the spawner for the workshop can control what happens when the user is finished. 42 | -------------------------------------------------------------------------------- /workshop/content/exercises/04-building-image.md: -------------------------------------------------------------------------------- 1 | The recommended approach to distribute a workshop is to create a container image which packages up your workshop. This way, the workshop content, along with all the command line tools, runtime language environments and applications used to display the workshop content are together. 2 | 3 | You can use `docker` or `buildah` to build the image using the supplied `Dockerfile`. If you have no need to install extra system packages, you could also use Source-to-Image (S2I) to build the image as the base image used in a `docker` type build, can also be used as an S2I builder. 4 | 5 | In this workshop the ability to build the image using the `Dockerfile` will be used. Rather than use `docker` or `buildah`, we will setup a build configuration in OpenShift, pushing the workshop content using a binary input build. This will be done using the scripts provided with the workshop scripts package you added as a Git submodule. 6 | 7 | To build our custom workshop image, we first need to deploy the sample workshop. To do this run: 8 | 9 | ```execute 10 | .workshop/scripts/deploy-personal.sh --settings=develop 11 | ``` 12 | 13 | Note that the `--settings=develop` option is a special option being used in this case where we are deploying the sample workshop from within a workshop, and wouldn't always be used. We will dive further into defining the workshop settings later. 14 | 15 | When run, the deployment script will create a deployment called `lab-sample-workshop`. The script will only return once the deployment has completed. 16 | 17 | Now run: 18 | 19 | ```execute 20 | oc get is -l app=lab-sample-workshop 21 | ``` 22 | 23 | You should see that an image stream has been created corresponding to the workshop image used in the deployment. By default the image stream is set up to use an image from `quay.io` for the original sample workshop content. We need to override that image with one built from our copy of the sample workshop content. 24 | 25 | To do this, run: 26 | 27 | ```execute 28 | .workshop/scripts/build-workshop.sh 29 | ``` 30 | 31 | This script will create a binary input build and push up the workshop content from the current directory, overriding the original sample workshop content from the image pulled from `quay.io`. 32 | 33 | Once the build has completed, wait for the re-deployment of the workshop to finish by running: 34 | 35 | ```execute 36 | oc rollout status dc/lab-sample-workshop 37 | ``` 38 | 39 | Then run: 40 | 41 | ```execute 42 | oc get route/lab-sample-workshop 43 | ``` 44 | 45 | This should show the hostname to access the newly deployed workshop content from your browser. In this case you should also be able to click on: 46 | 47 | https://lab-sample-workshop-%project_namespace%.%cluster_subdomain% 48 | 49 | You will be prompted to login. Use `workshop` for both the username and password. 50 | 51 | The content displayed at this point is that for your copy of the sample workshop. This is where you would start modifying the content. 52 | -------------------------------------------------------------------------------- /workshop/content/exercises/16-multiple-users.md: -------------------------------------------------------------------------------- 1 | If you need to run a workshop for many users, instead of the `deploy-personal.sh` script under the `.workshop/scripts` directory, you can use the `deploy-spawner.sh` script. 2 | 3 | This script supports a number of different modes for spawning multiple instances of a workshop. These are: 4 | 5 | * `learning-portal` - Used for workshops, or a permanent interactive learning portal where users are anonymous and may do a workshop at any time. Users are given temporary access as a service account user, with a single temporary project. When a workshop is completed, or the allowed time expires, the service account and project are automatically deleted. 6 | 7 | * `hosted-workshop` - Used to run a supervised workshop where each user is provided with separate login credentials for an existing user of the OpenShift cluster in which the workshop is being run, in order to login. Users can perform any action in the cluster that the OpenShift user can do, including being able to create multiple projects, if the cluster user quota configuration permits it. 8 | 9 | * `terminal-server` - Similar to the hosted workshop configuration. It defaults to only supplying an interactive terminal in the browser using the workshop terminal base image. If a workshop using the full workshop dashboard base is used with this configuration, no embedded web console is provided. 10 | 11 | * `user-workspace` - Similar to the learning portal configuration, but users need to login through Keycloak. Users are given access as a service account user, with a single project. The service account and project are dedicated to the user and will still be present if the user were to leave and come back at a future time. This provides a place where users can do ongoing work, but without needing to allocate users in OpenShift itself. 12 | 13 | * `jumpbox-server` - Users login through Keycloak. It defaults to only supplying an interactive terminal in the browser using the workshop terminal base image. The user has no access to the cluster itself to do anything. The terminal would be used to access a separate system. 14 | 15 | Except for `jumpbox-server`, multi user deployments using the workshop spawner require that you have cluster admin access. 16 | 17 | When designing workshop content, you should keep in mind how you will deploy it. This is because the environment provided for a personal instance of a workshop, and the various ways of deploying it for multiple users, can differ. 18 | 19 | By default when you use `deploy-spawner.sh`, it will use the `learning-portal` configuration for the workshop spawner. If you work out that a workshop requires a different mode when being run for multiple users, you can set the `SPAWNER_MODE` setting in the `.workshop/settings.sh` file. 20 | 21 | If you want to work on your workshop content when using the workshop spawner, you still can. Run `build-workshop.sh` as you did previously. This time the workshop instance wouldn't be automatically restarted though. To do that, and have the new version of the workshop image used, select "Restart Workshop" from the menu of the dashboard for your workshop session run from the spawner. 22 | -------------------------------------------------------------------------------- /workshop/content/exercises/15-deploy-settings.md: -------------------------------------------------------------------------------- 1 | When you deployed the sample workshop you created during this workshop, you used the `deploy-personal.sh` script. This can be used with your own workshop image where a user is only interested in deploying the workshop image for their own use. 2 | 3 | When this was done, the option `--settings=develop` was used. This was used in part because of how this workshop has been deployed. It isn't something you have to use, and instead, you would often use only: 4 | 5 | ``` 6 | .workshop/scripts/deploy-personal.sh 7 | ``` 8 | 9 | The purpose of the `--settings` option is to allow additional custom settings to be supplied beyond the default settings for a specific workshop. This would be used where you need to override settings when deploying the workshop for a specific use case or during development of the workshop content. 10 | 11 | In this case, access to the workshop environment would normally be gated using user authentication provided by the OpenShift cluster, with only a project admin of the project having access to the workshop. In deploying the sample workshop as part of the workshop, we couldn't use that way of handling authentication. 12 | 13 | Instead of relying on user authentication provided by the OpenShift cluster, you can though provide the `AUTH_USERNAME` and `AUTH_PASSWORD` settings, to enable access using HTTP authentication. What was therefore done, was that the file `.workshop/develop-settings.sh` was included with the sample workshop content: 14 | 15 | ```execute 16 | cat .workshop/develop-settings.sh 17 | ``` 18 | 19 | The `--settings=develop` option was used to specify that this additional settings file should be read. This was read after the `.workshop/settings.sh` file was read. 20 | 21 | This enabled the specific workshop deployment to be customised as necessary. It was used here to change how authentication was handled when deploying a personal workshop when working on the workshop content. You could use it to refer to a different settings file for different versions of the workshop, using a different workshop image, or by specifying a different workshop file to enable different modules. 22 | 23 | In addition to using the `--settings` option to refer to a set of override settings for a workshop, you can override individual settings on the command line using the `--override` option. 24 | 25 | In this case, instead of using the `--settings` option to refer to an override settings file containing settings for `AUTH_USERNAME` and `AUTH_PASSWORD`, you could have used: 26 | 27 | ``` 28 | .workshop/scripts/deploy-personal.sh --override AUTH_USERNAME=workshop --override AUTH_PASSWORD=workshop 29 | ``` 30 | 31 | Where you have multiple settings you need to override, but you don't want the file that contains them to be part of the workshop itself, you can instead write them all to a distinct temporary file and then use `--override` option, but where the value supplied begins with `@` followed by the path to the temporary file. 32 | 33 | ``` 34 | cat > /tmp/override-settings.sh << EOF 35 | AUTH_USERNAME=workshop 36 | AUTH_PASSWORD=workshop 37 | EOF 38 | 39 | .workshop/scripts/deploy-personal.sh --override @/tmp/override-settings.sh 40 | ``` 41 | -------------------------------------------------------------------------------- /workshop/content/exercises/08-embedded-links.md: -------------------------------------------------------------------------------- 1 | URLs can be included in workshop content. This can be the literal URL, or the Markdown syntax for including and labelling a URL. What happens when a user clicks on a URL, will depend on the specific URL. 2 | 3 | In the case of the URL being an external web site, when the URL is clicked, the URL will be opened in a new browser tab or window. 4 | 5 | * [External](https://www.openshift.com) 6 | 7 | When the URL is a relative page referring to another page which is a part of the workshop content, the page will replace the current workshop page. 8 | 9 | * [Internal](08-embedded-links) 10 | 11 | A URL can be provided using a data variable. This could be one of the builtin data variables, or one you have added to the workshop config. 12 | 13 | You can also define a URL where components of the URL are provided by data variables. Data variables useful in this content are `project_namespace` and `cluster_subdomain` as they can be used to create a URL to an application deployed from a workshop. 14 | 15 | * [Application](https://lab-sample-workshop-%project_namespace%.%cluster_subdomain%) - https://lab-sample-workshop-%project_namespace%.%cluster_subdomain% 16 | 17 | A number of the builtin data variables which provide a URL path value are treated in a special way when clicked. 18 | 19 | * `terminal_url` - When clicked the terminal tab will be selected and brought to the front if not already visible. 20 | * `console_url` - When clicked the console tab will be selected and brought to the front if not already visible. 21 | * `slides_url` - When clicked the slides tab will be selected and brought to the front if not already visible. 22 | 23 | In the case of `terminal_url`, you can append a path to the URL identifying a specific terminal session. In this case a new browser tab or window will be opened on that session. 24 | 25 | * [Terminal](%terminal_url%) - %terminal_url% 26 | * [Session](%terminal_url%/session/3) - %terminal_url%/session/3 27 | 28 | In the case of `console_url`, you can append a path to the URL, and the console tab, as well as being brought to the front if not already visible, will be opened on the given URL path. 29 | 30 | * [Projects](%console_url%) - %console_url% 31 | * [Status](%console_url%/overview/ns/%project_namespace%) - %console_url%/overview/ns/%project_namespace% 32 | * [Events](%console_url%/k8s/ns/%project_namespace%/events) - %console_url%/k8s/ns/%project_namespace%/events 33 | * [Pods](%console_url%/k8s/ns/%project_namespace%/pods) - %console_url%/k8s/ns/%project_namespace%/pods 34 | 35 | In the case of `slides_url`, the slides will be brought to the front if not already visible. If you are using reveal.js for the slides and you have history enabled, or are using section IDs to support named links, you can use an anchor to a specific slide and that specific slide will be opened. 36 | 37 | * [Slides](%slides_url%) - %slides_url% 38 | * [Questions](%slides_url%#/questions) - %slides_url%#/questions 39 | -------------------------------------------------------------------------------- /workshop/content/exercises/02-workshop-scripts.md: -------------------------------------------------------------------------------- 1 | In order to make deployment of a workshop easier, for both personal use and if running a multi user workshop, a set of deployment scripts are provided which wrap up all the steps required to deploy the workshop. These scripts are supplied as part of the Git repository: 2 | 3 | * https://github.com/openshift-homeroom/workshop-scripts 4 | 5 | To use the scripts with your workshop, they should be included into your Git repository as a Git submodule. This is done, rather than making a copy of the files into your Git repository, so it is easier to update your workshop to the latest scripts at any time. 6 | 7 | Once you have setup the Git repository for your own workshop using one of the sample workshops as a starting point, to add the workshop scripts, run the following commands: 8 | 9 | ```execute 10 | rmdir .workshop/scripts 11 | ``` 12 | 13 | This removes the `.workshop/scripts` directory that may exist when unpacking the sample workshop. 14 | 15 | Next configure Git to add the `workshop-scripts` Git repository as a Git submodule: 16 | 17 | ```execute 18 | git submodule add -b stable/1.x https://github.com/openshift-homeroom/spawner-scripts.git .workshop/scripts 19 | ``` 20 | 21 | Then checkout a copy of the Git submodule: 22 | 23 | ```execute 24 | git submodule update --remote 25 | ``` 26 | 27 | You should see that the `.workshop/scripts` directory now contains a number of different scripts and files. 28 | 29 | ```execute 30 | ls -las .workshop/scripts 31 | ``` 32 | 33 | One of these files is the `default-settings.sh` file. View the contents by running: 34 | 35 | ```execute 36 | cat .workshop/scripts/default-settings.sh 37 | ``` 38 | 39 | This file includes variables which indicate what versions of the workshop images should be used when using this version of the workshop scripts. The one we are interested in at this point is the `DASHBOARD_IMAGE` variable. 40 | 41 | This indicates the version of the workshop dashboard base image which should be used. This needs to match what is used in the `FROM` statement of the `Dockerfile` in the current directory, used to build your workshop: 42 | 43 | ```execute 44 | cat Dockerfile 45 | ``` 46 | 47 | Edit the `Dockerfile` if the image is different and set it to the required version, or run: 48 | 49 | ```execute 50 | (. .workshop/scripts/default-settings.sh; sed -i -e "s%^FROM .*$%FROM $DASHBOARD_IMAGE%" Dockerfile) 51 | ``` 52 | 53 | As well as the change to the `Dockerfile`, it is also necessary to edit the `.workshop/settings.sh` file. This file contains the name used for the workshop deployment. 54 | 55 | ```execute 56 | cat .workshop/settings.sh 57 | ``` 58 | 59 | The `WORKSHOP_NAME` variable should be changed to `lab-sample-workshop`, to match the name used for the Git repository directory. 60 | 61 | ```execute 62 | sed -i -e "s/^WORKSHOP_NAME=.*$/WORKSHOP_NAME=lab-sample-workshop/" .workshop/settings.sh 63 | ``` 64 | 65 | When both changes have been made, add all the changes to your Git repository: 66 | 67 | ```execute 68 | git add . 69 | ``` 70 | 71 | and commit the changes: 72 | 73 | ```execute 74 | git commit -m 'Add workshop scripts submodule.' 75 | ``` 76 | 77 | If in the future you want to update the version of the workshop scripts used with your workshop, run again the `git submodule update --remote` command. Then update the version of the dashboard base image in the `Dockerfile` to match. 78 | -------------------------------------------------------------------------------- /workshop/content/exercises/01-sample-workshop.md: -------------------------------------------------------------------------------- 1 | To get you started with your own workshop content, a number of sample Git repositories are provided. Which you use will depend on whether you prefer to use Markdown or AsciiDoc formatting for content. These are: 2 | 3 | * https://github.com/openshift-homeroom/lab-markdown-sample 4 | * https://github.com/openshift-homeroom/lab-asciidoc-sample 5 | 6 | You have two options for how you can get started with these sample Git repositories. 7 | 8 | The first option is to use the GitHub feature for creating a new repository from a [Git repository template](https://help.github.com/en/articles/creating-a-repository-from-a-template). This is different to forking an existing Git repository on GitHub, in that it creates a fresh repository with the latest content from the original Git repository. In creating a Git repository using this feature, it does not inherit any commit history from the original, and it is not linked to the original. Once you have created your copy of the Git repository, you can check out a copy to your own machine and start working on it. 9 | 10 | The second option is to download a copy of one of the sample Git repositories from the releases page for that Git repository. From this you can then create a local Git repository, and push it up to a Git repository hosting service of your choice. 11 | 12 | In this workshop we will use the second option of downloading a copy of the sample Git repository from the GitHub releases archive. 13 | 14 | To download the sample workshop using Markdown formatting, run: 15 | 16 | ```execute 17 | curl -sL -o /tmp/lab-markdown-sample.tar.gz https://github.com/openshift-homeroom/lab-markdown-sample/archive/1.5.tar.gz 18 | ``` 19 | 20 | then unpack it into a sub directory, by running: 21 | 22 | ```execute 23 | mkdir -p lab-sample-workshop && tar --strip-components 1 -C lab-sample-workshop -xzf /tmp/lab-markdown-sample.tar.gz 24 | ``` 25 | 26 | This should leave you with the `lab-sample-workshop` sub directory. If you were creating your own workshop, you would name this after what your own workshop is on. 27 | 28 | Our convention is to always prefix the directory name, and thus the Git repository name where it is being hosted, with the `lab-` prefix. This way it stands out as a workshop or lab when you have a whole bunch of Git repositories on the same Git hosting service account or organisation. 29 | 30 | Note that you should not make the name you use for a workshop too long, else the DNS host name used for applications deployed from the workshop, when using certain modes of the workshop spawner, can exceed the 63 character limit. This is because the workshop deployment name is used as part of the project name for each session, which will in turn be used in the DNS host names generated by OpenShift. It is suggested to keep the workshop name, and thus your repository name to 25 characters or less. 31 | 32 | With the sample workshop downloaded, change your working directory so you are in the top level directory for the workshop. 33 | 34 | ```execute 35 | cd lab-sample-workshop 36 | ``` 37 | 38 | Create a Git repository from the directory by running: 39 | 40 | ```execute 41 | git init 42 | ``` 43 | 44 | This is so you can track changes you make. 45 | 46 | Now add everything into Git: 47 | 48 | ```execute 49 | git add . 50 | ``` 51 | 52 | and commit it as the initial set of files: 53 | 54 | ```execute 55 | git commit -m 'Initial files.' 56 | ``` 57 | 58 | We will leave it up to you to work out how to later push your workshop content up to a Git hosting service. 59 | -------------------------------------------------------------------------------- /workshop/content/exercises/06-page-formatting.md: -------------------------------------------------------------------------------- 1 | Individual module files can use either Markdown or AsciiDoc markup formats. The extension used on the file should be `.md` or `.adoc`, corresponding to which formatting markup style you want to use. The extension is though always left off when listing the module name in the YAML files used for configuration. 2 | 3 | In conjunction with the standard [Markdown](https://github.github.com/gfm/) and [AsciiDoc](http://asciidoc.org/), additional annotations can be applied to code blocks. The annotations are used to indicate that a user can click on the code block and have it copied to the terminal and executed, or copy the code block into the paste buffer so it can be pasted into another window. 4 | 5 | If using Markdown, to annotate a code block so that it will be copied to the terminal and executed, use: 6 | 7 | 
```execute
 8 | echo upper
 9 | ```
10 | 11 | Using this, we have: 12 | 13 | ```execute 14 | echo upper 15 | ``` 16 | 17 | When you click on the code block the command will be executed in the upper terminal. 18 | 19 | If using AsciiDoc, you would instead use the `role` annotation in an existing code block: 20 | 21 | 
[source,bash,role=execute]
22 | ----
23 | echo upper
24 | ----
25 |
26 | 27 | To have a command be executed in the lower terminal, use `execute-2` instead of `execute`: 28 | 29 | 
```execute-2
30 | echo lower
31 | ```
32 | 33 | Using this, we have: 34 | 35 | ```execute-2 36 | echo lower 37 | ``` 38 | 39 | Note that having two terminals is an option and not the default. For this workshop two are displayed because the `Dockerfile` files set the `TERMINAL_TAB=split` environment variable. If you didn't need the terminal tab to be split and two terminal sessions shown, remove the setting for this environment variable. 40 | 41 | In the case where you do have two terminals, if you want to be clear when a command is being executed in the upper terminal, instead of `execute`, you can use `execute-1` for the annotation on the code block. 42 | 43 | In most cases, a command you execute would complete straight away. If you need to run a command that never returns, with the user needing to interrupt it to stop it, you can use the special string `` in the code block. 44 | 45 | 
```execute
46 | <ctrl+c>
47 | ```
48 | 49 | You could then have: 50 | 51 | ```execute 52 | sleep 3600 53 | ``` 54 | 55 | followed by: 56 | 57 | ```execute 58 | 59 | ``` 60 | 61 | When the user clicks on the latter, the prior command will be interrupted. 62 | 63 | Instead of executing a command, you wanted the content of the code block to be copied into the paste buffer, you can use: 64 | 65 | 
```copy
66 | echo copy
67 | ```
68 | 69 | Yielding: 70 | 71 | ```copy 72 | echo copy 73 | ``` 74 | 75 | After clicking on this code block, you could then paste the content into another window. 76 | 77 | If you have a situation where the text being copied should be modified before use, you can denote this special case by using `copy-and-edit` instead of `copy`. The text will still be copied to the paste buffer, but will be displayed in the browser in a way to highlight that it needs to be changed before use. 78 | 79 | 
```copy-and-edit
80 | echo copy-and-edit
81 | ```
82 | 83 | Yielding: 84 | 85 | ```copy-and-edit 86 | echo copy-and-edit 87 | ``` 88 | 89 | For AsciiDoc, similar to `execute`, you can add the `role` of `copy` or `copy-and-edit`: 90 | 91 | 
[source,bash,role=copy]
92 | ----
93 | echo copy
94 | ----
95 |
96 | -------------------------------------------------------------------------------- /workshop/content/exercises/12-build-and-setup.md: -------------------------------------------------------------------------------- 1 | When building the container image for a workshop, you can include any additional files that may be required to do the workshop. This can include source code files or scripts. The supplied `Dockerfile` will ensure that these files are copied into the home directory for the workshop environment. This is the same directory used as the working directory for the embedded terminals. 2 | 3 | If you need to perform any extra steps during the build process for the container image, you can add these steps to the executable `.workshop/build` script file. 4 | 5 | The default build script used in the sample workshop is: 6 | 7 | ``` 8 | #!/bin/bash 9 | 10 | # This 'build' script is where you can add steps that should be run when 11 | # building the image for your custom workshop. 12 | 13 | # Move the workshop content to '/opt/app-root/workshop'. It could be left 14 | # at it's default location of '/opt/app-root/src/workshop', but by moving it, 15 | # it is out of view of the user doing the workshop and they aren't likely to 16 | # delete it by accident and break the display of the workshop content. 17 | 18 | mv workshop /opt/app-root/workshop 19 | 20 | # Also delete some of the other files from the top of the Git repository we 21 | # don't need for running the workshop. 22 | 23 | rm -f Dockerfile README.md LICENSE 24 | 25 | # If the workshop requires Git, it is necessary to set some defaults for 26 | # the name and email of the user for Git. 27 | 28 | git config --global user.email "you@example.com" 29 | git config --global user.name "Your Name" 30 | ``` 31 | 32 | This can be used to perform tasks like remove any extra files which are not needed for the workshop and which may confuse users were they present. If the workshop uses Git, you can set any global options required to configure Git which are not dependent on a specific session. You could also checkout copies of remote Git repositories, download any other required files or application source code, and build any applications. 33 | 34 | One special step you can add to the build script is to move the complete `workshop` directory containing the workshop content and slides, to the `/opt/app-root/workshop` directory. This is an alternate location for placing the workshop content. By moving this, it will not be visible to the user in the home directory which lessons the risk of them removing it and breaking the rendering of the workshop content. 35 | 36 | Because the build script is run as a non privileged user, you cannot add steps to this script which need to run as the `root` user, such as install system packages. If you need to run any steps as the `root` user, you will need to add these to the `Dockerfile` and be using a `docker` type build and not an S2I build. 37 | 38 | When the container image for the workshop is deployed, if you need to run extra steps which depend on the workshop environment for a specific session, you can add them to the executable `.workshop/setup` script. As with the build script, this is run as a non privileged user. 39 | 40 | The setup script will be run before the web application which provides the workshop environment dashboard. Any steps you add will therefore block the start up of the workshop environment. You should avoid doing anything which takes a non trivial amount of time. 41 | 42 | Where the deployment method for a workshop environment automatically logs in the user to the OpenShift cluster, the setup script can be used to run commands against the OpenShift cluster. This could include pre-deploying applications on behalf of the user. Any such actions must though be tolerant of being run more than once, as they may be run a further time were the container to be restarted. 43 | -------------------------------------------------------------------------------- /workshop/content/exercises/05-workshop-config.md: -------------------------------------------------------------------------------- 1 | There are different ways you can setup configuration for a workshop. The way used in the sample workshops is through YAML files. 2 | 3 | The `workshop/modules.yaml` file provides details of available modules which make up your workshop, and data variables for use in content. 4 | 5 | In the case of the list of modules, not all modules may end up being used. This is because this list represents the full set of modules you have available and might use. You may want to run variations of your workshop, such as for different programming languages. As such, which modules are active and will be used for a specific workshop are listed in the separate `workshop/workshop.yaml` file, along with the name to be given to the workshop when using that set of modules. 6 | 7 | By default the `workshop.yaml` file will be used to drive what modules are used. Where you do have variations as to what content should be used, you can provide multiple workshop files with different names. You might for example instead provide `workshop-java.yaml` and `workshop-python.yaml`. 8 | 9 | Where you have multiple workshop files, and don't have the default `workshop.yaml` file, you can specify the default workshop file to use by setting the `WORKSHOP_FILE` environment variable in the `Dockerfile`, to the name of the workshop file. The environment variable will be able to be overridden for a deployment to select a different workshop file when necessary. 10 | 11 | The format for listing the available modules in the `workshop/modules.yaml` file is: 12 | 13 | ``` 14 | modules: 15 | workshop-overview: 16 | name: Workshop Overview 17 | exit_sign: Setup Environment 18 | setup-environment: 19 | name: Setup Environment 20 | exit_sign: Start Workshop 21 | exercises/01-sample-content: 22 | name: Sample Content 23 | workshop-summary: 24 | name: Workshop Summary 25 | exit_sign: Finish Workshop 26 | ``` 27 | 28 | Each available module is listed under `modules`, where the name used corresponds to the path to the file containing the content for that module, with any extension identifying the content type left off. 29 | 30 | For each module, set the `name` field to the title to be displayed for that module. If no fields are provided and `name` is not set, the title for the module will be calculated from the name of the module file. The purpose of the `exit_sign` field will be discussed later when looking at page navigation. 31 | 32 | The corresponding `workshop/workshop.yaml` file, where all available modules were being used, would have the format: 33 | 34 | ``` 35 | name: Markdown Sample 36 | 37 | modules: 38 | activate: 39 | - workshop-overview 40 | - setup-environment 41 | - exercises/01-sample-content 42 | - workshop-summary 43 | ``` 44 | 45 | The top level `name` field in this file is the title to be displayed for the complete workshop. It will be shown in the banner for the workshop content when viewing the workshop environment in your web browser. 46 | 47 | The `modules.activate` field is a list of modules to be used for the workshop. The names in this list must match the names as they appear in the modules file. 48 | 49 | The first change you will want to make is to set the title for your workshop by changing the `name` field. 50 | 51 | For this workshop, change it to `Sample Workshop`. You can use `vi` or `nano` in the terminal, or you can run: 52 | 53 | ```execute 54 | sed -i -e 's/Markdown Sample/Sample Workshop/' workshop/workshop.yaml 55 | ``` 56 | 57 | Having made a change, you can rebuild the image and redeploy it by again running: 58 | 59 | ```execute 60 | .workshop/scripts/build-workshop.sh 61 | ``` 62 | 63 | Wait for the re-deployment by running: 64 | 65 | ```execute 66 | oc rollout status dc/lab-sample-workshop 67 | ``` 68 | 69 | Once complete, [refresh the page](https://lab-sample-workshop-%project_namespace%.%cluster_subdomain%) for your workshop to check the change works. 70 | 71 | If you were happy with the change, you would then go onto adding and committing the change to your Git repository. This modify/build/refresh process is how you would go about working on your content and testing it. 72 | -------------------------------------------------------------------------------- /workshop/content/exercises/07-data-variables.md: -------------------------------------------------------------------------------- 1 | When creating page content, you can reference a number of pre-defined data variables. The values of the data variables will be substituted into the page when rendered in the users browser. 2 | 3 | The workshop environment provides the following built-in data variables. 4 | 5 | * `username` - The identity of the user doing the workshop. This will usually only be set when the workshop is deployed in a multi user deployment. This is different from the name of the service account the workshop environment is running as. 6 | * `project_namespace` - The name of the OpenShift project the workshop environment is linked to and into which any deployed applications will run. Depending on how the workshop has been deployed, this may be the same project the workshop environment is running in, or may be a distinct project created for the workshop in advance. 7 | * `cluster_subdomain` - The subdomain used in generated route hostnames of applications deployed to the OpenShift cluster. 8 | * `base_url` - The root URL path for the workshop content. 9 | * `terminal_url` - The root URL path for the terminal application. 10 | * `console_url` - The root URL path for the embedded web console. 11 | * `slides_url` - The root URL path for slides if provided. 12 | 13 | To use a data variable within the page content, surround it each side with the character `%`. 14 | 15 | 
%username%
16 | 17 | This can be done inside of code blocks, as well as in URLs. 18 | 19 | 
http://lab-sample-workshop-%project_namespace%.%cluster_subdomain%/
20 | 21 | For the way in which this workshop has been deployed, the values of these variables are: 22 | 23 | * `username`: %username% 24 | * `project_namespace`: %project_namespace% 25 | * `cluster_subdomain`: %cluster_subdomain% 26 | * `base_url`: %base_url% 27 | * `console_url`: %console_url% 28 | * `terminal_url`: %terminal_url% 29 | * `slides_url`: %slides_url% 30 | 31 | You can introduce your own data variables by listing them in the `workshop/modules.yaml` file. A data variable is defined as having a default value, but where the value will be overridden if an environment variable of the same name is defined. 32 | 33 | The field under which the data variables should be specified is `config.vars`. 34 | 35 | ``` 36 | config: 37 | vars: 38 | - name: OC_VERSION 39 | value: undefined 40 | - name: KUBECTL_VERSION 41 | value: undefined 42 | ``` 43 | 44 | In this case, the `OC_VERSION` and `KUBECTL_VERSION` environment variables are set by the workshop environment. The values they have for this workshop are: 45 | 46 | * `OC_VERSION`: %OC_VERSION% 47 | * `KUBECTL_VERSION`: %KUBECTL_VERSION% 48 | 49 | Where you want to use a name for a data variable which is different to the environment variable name, you can add a list of `aliases`. 50 | 51 | ``` 52 | config: 53 | vars: 54 | - name: LANGUAGE 55 | value: undefined 56 | aliases: 57 | - WORKSHOP_LANG 58 | ``` 59 | 60 | The environment variables with names given in the list of aliases will be checked first, then the environment variable with the same name as the data variable. If no environment variables with those names are set, then the default value will be used. 61 | 62 | The default value for a data variable can be overridden for a specific workshop by setting it in the corresponding workshop file. For example, `workshop/workshop-python.yaml` might contain: 63 | 64 | ``` 65 | vars: 66 | LANGUAGE: python 67 | ``` 68 | 69 | If you need more control over setting the values of data variables, you can provide the file `workshop/config.js`. The form of this file should be: 70 | 71 | ``` 72 | function initialize(workshop) { 73 | workshop.load_workshop(); 74 | 75 | if (process.env['WORKSHOP_FILE'] == 'workshop-python.yaml') { 76 | workshop.data_variable('LANGUAGE', 'python'); 77 | } 78 | } 79 | 80 | exports.default = initialize; 81 | 82 | module.exports = exports.default; 83 | ``` 84 | 85 | This Javascript code will be loaded and the `initialize()` function called to load the workshop configuration. You can then use the `workshop.data_variable()` function to set up any data variables 86 | 87 | Because it is Javascript, you can write any code you need to query process environment variables and set data variables based on those. This might include creating composite values constructed from multiple environment variables. You could even download data variables from a remote host. 88 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | 2 | Apache License 3 | Version 2.0, January 2004 4 | http://www.apache.org/licenses/ 5 | 6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 7 | 8 | 1. Definitions. 9 | 10 | "License" shall mean the terms and conditions for use, reproduction, 11 | and distribution as defined by Sections 1 through 9 of this document. 12 | 13 | "Licensor" shall mean the copyright owner or entity authorized by 14 | the copyright owner that is granting the License. 15 | 16 | "Legal Entity" shall mean the union of the acting entity and all 17 | other entities that control, are controlled by, or are under common 18 | control with that entity. For the purposes of this definition, 19 | "control" means (i) the power, direct or indirect, to cause the 20 | direction or management of such entity, whether by contract or 21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 22 | outstanding shares, or (iii) beneficial ownership of such entity. 23 | 24 | "You" (or "Your") shall mean an individual or Legal Entity 25 | exercising permissions granted by this License. 26 | 27 | "Source" form shall mean the preferred form for making modifications, 28 | including but not limited to software source code, documentation 29 | source, and configuration files. 30 | 31 | "Object" form shall mean any form resulting from mechanical 32 | transformation or translation of a Source form, including but 33 | not limited to compiled object code, generated documentation, 34 | and conversions to other media types. 35 | 36 | "Work" shall mean the work of authorship, whether in Source or 37 | Object form, made available under the License, as indicated by a 38 | copyright notice that is included in or attached to the work 39 | (an example is provided in the Appendix below). 40 | 41 | "Derivative Works" shall mean any work, whether in Source or Object 42 | form, that is based on (or derived from) the Work and for which the 43 | editorial revisions, annotations, elaborations, or other modifications 44 | represent, as a whole, an original work of authorship. For the purposes 45 | of this License, Derivative Works shall not include works that remain 46 | separable from, or merely link (or bind by name) to the interfaces of, 47 | the Work and Derivative Works thereof. 48 | 49 | "Contribution" shall mean any work of authorship, including 50 | the original version of the Work and any modifications or additions 51 | to that Work or Derivative Works thereof, that is intentionally 52 | submitted to Licensor for inclusion in the Work by the copyright owner 53 | or by an individual or Legal Entity authorized to submit on behalf of 54 | the copyright owner. For the purposes of this definition, "submitted" 55 | means any form of electronic, verbal, or written communication sent 56 | to the Licensor or its representatives, including but not limited to 57 | communication on electronic mailing lists, source code control systems, 58 | and issue tracking systems that are managed by, or on behalf of, the 59 | Licensor for the purpose of discussing and improving the Work, but 60 | excluding communication that is conspicuously marked or otherwise 61 | designated in writing by the copyright owner as "Not a Contribution." 62 | 63 | "Contributor" shall mean Licensor and any individual or Legal Entity 64 | on behalf of whom a Contribution has been received by Licensor and 65 | subsequently incorporated within the Work. 66 | 67 | 2. Grant of Copyright License. Subject to the terms and conditions of 68 | this License, each Contributor hereby grants to You a perpetual, 69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 70 | copyright license to reproduce, prepare Derivative Works of, 71 | publicly display, publicly perform, sublicense, and distribute the 72 | Work and such Derivative Works in Source or Object form. 73 | 74 | 3. Grant of Patent License. Subject to the terms and conditions of 75 | this License, each Contributor hereby grants to You a perpetual, 76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 77 | (except as stated in this section) patent license to make, have made, 78 | use, offer to sell, sell, import, and otherwise transfer the Work, 79 | where such license applies only to those patent claims licensable 80 | by such Contributor that are necessarily infringed by their 81 | Contribution(s) alone or by combination of their Contribution(s) 82 | with the Work to which such Contribution(s) was submitted. If You 83 | institute patent litigation against any entity (including a 84 | cross-claim or counterclaim in a lawsuit) alleging that the Work 85 | or a Contribution incorporated within the Work constitutes direct 86 | or contributory patent infringement, then any patent licenses 87 | granted to You under this License for that Work shall terminate 88 | as of the date such litigation is filed. 89 | 90 | 4. Redistribution. You may reproduce and distribute copies of the 91 | Work or Derivative Works thereof in any medium, with or without 92 | modifications, and in Source or Object form, provided that You 93 | meet the following conditions: 94 | 95 | (a) You must give any other recipients of the Work or 96 | Derivative Works a copy of this License; and 97 | 98 | (b) You must cause any modified files to carry prominent notices 99 | stating that You changed the files; and 100 | 101 | (c) You must retain, in the Source form of any Derivative Works 102 | that You distribute, all copyright, patent, trademark, and 103 | attribution notices from the Source form of the Work, 104 | excluding those notices that do not pertain to any part of 105 | the Derivative Works; and 106 | 107 | (d) If the Work includes a "NOTICE" text file as part of its 108 | distribution, then any Derivative Works that You distribute must 109 | include a readable copy of the attribution notices contained 110 | within such NOTICE file, excluding those notices that do not 111 | pertain to any part of the Derivative Works, in at least one 112 | of the following places: within a NOTICE text file distributed 113 | as part of the Derivative Works; within the Source form or 114 | documentation, if provided along with the Derivative Works; or, 115 | within a display generated by the Derivative Works, if and 116 | wherever such third-party notices normally appear. The contents 117 | of the NOTICE file are for informational purposes only and 118 | do not modify the License. You may add Your own attribution 119 | notices within Derivative Works that You distribute, alongside 120 | or as an addendum to the NOTICE text from the Work, provided 121 | that such additional attribution notices cannot be construed 122 | as modifying the License. 123 | 124 | You may add Your own copyright statement to Your modifications and 125 | may provide additional or different license terms and conditions 126 | for use, reproduction, or distribution of Your modifications, or 127 | for any such Derivative Works as a whole, provided Your use, 128 | reproduction, and distribution of the Work otherwise complies with 129 | the conditions stated in this License. 130 | 131 | 5. Submission of Contributions. Unless You explicitly state otherwise, 132 | any Contribution intentionally submitted for inclusion in the Work 133 | by You to the Licensor shall be under the terms and conditions of 134 | this License, without any additional terms or conditions. 135 | Notwithstanding the above, nothing herein shall supersede or modify 136 | the terms of any separate license agreement you may have executed 137 | with Licensor regarding such Contributions. 138 | 139 | 6. Trademarks. This License does not grant permission to use the trade 140 | names, trademarks, service marks, or product names of the Licensor, 141 | except as required for reasonable and customary use in describing the 142 | origin of the Work and reproducing the content of the NOTICE file. 143 | 144 | 7. Disclaimer of Warranty. Unless required by applicable law or 145 | agreed to in writing, Licensor provides the Work (and each 146 | Contributor provides its Contributions) on an "AS IS" BASIS, 147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 148 | implied, including, without limitation, any warranties or conditions 149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 150 | PARTICULAR PURPOSE. You are solely responsible for determining the 151 | appropriateness of using or redistributing the Work and assume any 152 | risks associated with Your exercise of permissions under this License. 153 | 154 | 8. Limitation of Liability. In no event and under no legal theory, 155 | whether in tort (including negligence), contract, or otherwise, 156 | unless required by applicable law (such as deliberate and grossly 157 | negligent acts) or agreed to in writing, shall any Contributor be 158 | liable to You for damages, including any direct, indirect, special, 159 | incidental, or consequential damages of any character arising as a 160 | result of this License or out of the use or inability to use the 161 | Work (including but not limited to damages for loss of goodwill, 162 | work stoppage, computer failure or malfunction, or any and all 163 | other commercial damages or losses), even if such Contributor 164 | has been advised of the possibility of such damages. 165 | 166 | 9. Accepting Warranty or Additional Liability. While redistributing 167 | the Work or Derivative Works thereof, You may choose to offer, 168 | and charge a fee for, acceptance of support, warranty, indemnity, 169 | or other liability obligations and/or rights consistent with this 170 | License. However, in accepting such obligations, You may act only 171 | on Your own behalf and on Your sole responsibility, not on behalf 172 | of any other Contributor, and only if You agree to indemnify, 173 | defend, and hold each Contributor harmless for any liability 174 | incurred by, or claims asserted against, such Contributor by reason 175 | of your accepting any such warranty or additional liability. 176 | 177 | END OF TERMS AND CONDITIONS 178 | 179 | APPENDIX: How to apply the Apache License to your work. 180 | 181 | To apply the Apache License to your work, attach the following 182 | boilerplate notice, with the fields enclosed by brackets "[]" 183 | replaced with your own identifying information. (Don't include 184 | the brackets!) The text should be enclosed in the appropriate 185 | comment syntax for the file format. We also recommend that a 186 | file or class name and description of purpose be included on the 187 | same "printed page" as the copyright notice for easier 188 | identification within third-party archives. 189 | 190 | Copyright [yyyy] [name of copyright owner] 191 | 192 | Licensed under the Apache License, Version 2.0 (the "License"); 193 | you may not use this file except in compliance with the License. 194 | You may obtain a copy of the License at 195 | 196 | http://www.apache.org/licenses/LICENSE-2.0 197 | 198 | Unless required by applicable law or agreed to in writing, software 199 | distributed under the License is distributed on an "AS IS" BASIS, 200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 201 | See the License for the specific language governing permissions and 202 | limitations under the License. 203 | --------------------------------------------------------------------------------