Merge pull request educates#185 from GrahamDumpleton/documentation-up…

…dates

Ad-doc documentation updates.

developer-docs/release-procedures.md

@@ -88,6 +88,11 @@ The public Educates documentation web site is updated from the `main` branch of
 
 Until a better system is created for handling adhoc updates to the public documentation web site, the following is recommended.
 
-If the `develop` branch is the same as `main`, add the documentation updates as normal to the `develop` branch and merge the `develop` branch into the `main` branch, then pull the `main` branch back into the `develop` branch to align the two branches.
-
-If the `develop` branch contains changes that cannot be merged into the `main` branch, merge any branch (manually created or via a pull request) containing the documentation updates into the `main` branch and then merge the `main` branch back into the `develop` branch. Merging changes from the `main` branch back into the `develop` branch may cause conflicts which will need to be resolved. When done, delete the original branch which contained the documentation updates, closing any pull request as necessary without merging it.
+1. Ensure that in your repository fork that the `main` branch is up to date with the main repository.
+2. When needing to make the documentation changes create the branch from the `main` branch instead of `develop`.
+3. Make the required changes in your documentation branch and push your branch to your repository fork.
+4. Create the pull request, ensure that it is being made relative to the `main` branch of the main repository and not `develop`.
+5. The pull request should then be merged to the `main` branch of the main repository.
+6. The `main` branch of the main repository should then be merged back into the `develop` branch.
+
+This process should only be used to make changes which affect the `project-docs` and `developer-docs` directories and which need to be made public in the `main` repository outside of the normal release schedule.

project-docs/workshop-content/building-an-image.md

@@ -1,7 +1,7 @@
 Building an Image
 =================
 
-Although it is recommended to use extension packages to bundle up additional applications needed by workshops, and overlay those on the standard workshop base image when a workshop session is started, it is possible to build your own custom workshop base images. Because this results in a hard dependency on a specific version of the workshop base image, it can result in workshop images which may not work with a newer Educates version. As such, only use this ability if you feel there is no other choice.
+Although it is recommended to use [extension packages](adding-extension-packages) to bundle up additional applications needed by workshops, and overlay those on the standard workshop base image when a workshop session is started, it is possible to build your own custom workshop base images. Because this results in a hard dependency on a specific version of the workshop base image, it can result in workshop images which may not work with a newer Educates version. As such, only use this ability if you feel there is no other choice.
 
 Structure of the Dockerfile
 ---------------------------

project-docs/workshop-content/working-on-content.md

@@ -122,6 +122,22 @@ By disabling reserved sessions a new workshop session will always be created on
 
 Note that there can be a slight delay in being able to create a new workshop as the existing workshop session will need to be shutdown first. The new workshop session may also take some time to start if an updated version of the workshop image has to be pulled down.
 
+Accessing workshop error logs
+-----------------------------
+
+If workshop content is not able to be downloaded due to an error, a setup script included with the workshop content fails, or workshop instructions cannot be rendered when using the Hugo renderer, an error dialog will be displayed when the workshop session dashboard is displayed. The dialog will point you at the error logs for details. You have two options for finding details of the errors in these cases.
+
+The first way is to determine the name of the deployment for the workshop session and which namespace it is in, and use the ``kubectl logs`` command to access the logs. 
+
+The second and easier way if you have access to the workshop session dashboard, is to use the embedded terminal to look at the log files located under the directory ``$HOME/.local/share/workshop``.
+
+The two main log files are:
+
+* ``$HOME/.local/share/workshop/download-workshop.log``
+* ``$HOME/.local/share/workshop/setup-scripts.log``
+
+You can tell in which phase the error occurred, as there will be a corresponding marker file in the same directory, with same basename, but with ``.failed`` extension.
+
 Live updates to the content
 ---------------------------
 
@@ -135,6 +151,8 @@ This command will download any workshop content from the OCI artifact registry,
 
 Once the workshop content has been updated you can reload the current page of the workshop instructions by clicking on the reload icon on the dashboard while holding down the `<SHIFT>` key.
 
+When running this command, any errors which occur in downloading the workshop content, running the setup script, or rendering the workshop instructions, will be output to the terminal so this command can be used instead of consulting the logs to look for errors. Do be aware though that since this can be the second time setup scripts have run, the behaviour may not be the same as the first time they have run. So for original details of errors you will still need to look at the log files.
+
 Note that if using the `classic` renderer and additional pages were added to the workshop instructions, or pages renamed, you will need to restart the workshop renderer process. This can be done by running:
 
 ```

project-docs/workshop-content/workshop-instructions.md

@@ -1094,6 +1094,14 @@ If using the ``hugo`` renderer this can be done using:
 https://myapp-{{< param session_name >}}.{{< param ingress_domain >}}
 ```
 
+In the case of setting up the workshop instance to act as a proxy for a web application, you would also need to use the ``ingress_protocol`` data variable, which will be the HTTP protocol scheme used for accessing the workshop session.
+
+```text
+{{< param ingress_protocol >}}://myapp-{{< param session_name >}}.{{< param ingress_domain >}}
+```
+
+This is necessary as it will be the Educates installation which will dictate whether ``https`` or plain ``http`` would be used and as a workshop author you would not know in advance.
+
 Conditional rendering of content
 --------------------------------