Builds your workshops and enjoys it.
You can deploy wherever you want, but we test specifically for OpenShift
oc new-app osevg/workshopper -e <YOUR CONFIGURATION>
For example:
oc new-app osevg/workshopper \
-e CONTENT_URL_PREFIX=https://raw.githubusercontent.com/osevg/workshopper-content/master \
-e WORKSHOPS_URLS=https://raw.githubusercontent.com/osevg/workshopper-content/master/_workshops/roadshow.yml
You can deploy directly using Docker for example for testing purposes when developing workshop content. In the
following example, the workshop content (adocs, images, etc) are in the /home/lisa/workshop
directory on
your local machine:
docker run -p 8080:8080 \
-v /home/lisa/workshop:/app-data \
-e CONTENT_URL_PREFIX="file:///app-data" \
-e WORKSHOPS_URLS="file:///app-data/_workshop.yml" \
osevg/workshopper
Workshopper retrieves and renders the asciidoc workshop content from an external source using the env vars
configured. In order to skip hosting your asciidocs externally, you can build a new container image based on
osevg/workshopper
and package your asciidocs within the same image.
Add the following Dockerfile
in the root of your workshop content folder:
FROM osevg/workshopper:latest
ENV CONTENT_URL_PREFIX="file:///opt/data/workshopper-content"
ENV WORKSHOPS_URLS="file:///opt/data/workshopper-content/_cloud-native-roadshow.yml"
ENV DEFAULT_LAB="roadshow"
ADD *.adoc /opt/data/workshopper-content/
ADD *.yml /opt/data/workshopper-content/
ADD images /opt/data/workshopper-content/images
USER root
RUN chown jboss:root -R /opt/data && chmod 777 -R /opt/data
USER jboss
And then build and run the new image:
docker build -t prepackaged-workshopper .
docker run -p 8080:8080 prepackaged-workshopper:latest
Workshopper exposes a number of endpoints to render the workshops using fragment identifiers:
URI | Description |
---|---|
/ |
Displays the workshops list |
/#/workshop/[id] |
Display the workshop with the specified id |
/reload |
Release the workshop YAML files and reload content |
Content repository where to look for modules. The system will look for
- $CONTENT_URL_PREFIX/_config.yml for configuration
- $CONTENT_URL_PREFIX/_modules.yml for module definition
- $CONTENT_URL_PREFIX/{file name}.adoc for specific content files
If not specified, this variable is constructed from segments as described below.
If the $CONTENT_URL_PREFIX variable is not defined, constructs the $CONTENT_URL_PREFIX variable for Github repository as
CONTENT_URL_PREFIX = https://raw.githubusercontent.com/$GITHUB_REPOSITORY/$GITHUB_REF
If the two variables are not defined then are defaulted to osevg/workshopper-content
and master
pointing to the
latest content provided by the authors.
The system needs definition what the workshop should look like. It can work with single or multiple workshops in single one deployment.
You need to choose from
- $WORKSHOPS_LIST_URL for workshops (defines single URL for list file)
or
- $WORKSHOPS_URLS for workshops (direct specification of workshop URLs using comma separated list)
In case neither of these variables is specified, the $WORKSHOPS_URLS defaults to
https://raw.githubusercontent.com/osevg/workshopper-workshops/master/default_workshop.yml
to render sample workshop with all modules.
If the system has multiple workshops using the WORKSHOPS_LIST_URL or WORKSHOPS_URLS the system can automatically redirect to specific workshop specified using this variable.
$WORKSHOPS_LIST_URL points to yaml file that contains list of URLs contain workshop definition as described in $WORKSHOPS_URLS section.
Comma separated list of urls
WORKSHOPS_URLS = "<URL1>,<URL2>,<URL3>"
The urls point to yaml files describing specific workshop.
Workshop YAML file pulls together several (or all) content modules to build a "learning experience" for the end user.
The main sections are
id
- id to use to identify workshop in multi-workshop deployments (SHA-256 of it's URL unless specified)name
- display name of the workshoplogo
- logo to display on the workshop pagevars
- defines variable values to use in modulesrevision
- activate this revision for all modules unless specified for the modulemodules
- configure modules in this workshop
for example
id: testing
name: Testing workshop
logo: test.png
vars:
VARIABLE: value
revision: <revision name>
modules:
<module configuration>
The module configuration has two sections
activate
- list modules to include in the workshop (all modules are included unless specified)revisions
- set per-module revision
name: Testing workshop
logo: test.png
revision: revision1
modules:
activate:
- module2
revisions:
module1: revisionxy
Let's assume that the module definition has 2 modules (module1
and module2
) with module2
having dependency on
module1
. This workshop activates module2
and as it has dependency on module1
, both are going to be included in
the workshop. module1
is going to have revisionxy
while module2
will have revision1
.
_config.yml
contains basic configuration fo the system. Currently these is only one section
allowed in this file called vars
that defines most generic fallback values for variables used in the modules.
vars:
VARIABLE_X: something
_modules.yml
defines modules available in the content repository. The file has one main modules
section that
contains the key-value pair, where the key is module id and value is module definition.
modules:
module1:
module_definition
The module definition contains metadata describing the module
name
- display name of the modulerequires
- list of other module ids that are required to understand before starting this modulevars
- defines variable values to use in the modulerevisions
- configures content revisions
modules:
module1:
name: Module 1
vars:
VARIABLE1: value1
module2:
name: Module 2
vars:
VARIABLE2: value2
requires:
- module1
Revisions allow choosing between different content versions either by changing variable values or by choosing completely different content.
modules:
module1:
name: Module 1
vars:
VARIABLE1: value1
module2:
name: Module 2
vars:
VARIABLE2: value2
requires:
- module1
revisions:
revision_name:
vars:
VARIABLE2: value22
If no revision is chosen, then the value of $VARIABLE2
is "value2", However when revisoin revision_name
is active,
variable $VARIABLE2 value is "value22".
The content file is located in the root of the content repository and follows the naming scheme module-id.adoc
. When
the content should be in a subdirectory, the module name reflects that by using the _
characted.
modules:
module1:
name: Module 1
sub_module2:
name: Module 2
This modules definition would have two asciidoc files
├── _config.yml
├── _modules.yml
├── module1.adoc
└── sub
└── module2.adoc
Variable for substitution in modules can be defined in these places
- _config.yml
- _modules.yml
- $WORKSHOPS_LIST_URL / $WORKSHOPS_URLS
- Environment variables
where the priority is
_config.yml < _modules.yml < $WORKSHOPS_LIST_URL / $WORKSHOPS_URLS < Environment variables
i.e. environment variables override all the other definitions.