From 576006af841f66f2a573e0ac9de132ba9c8612bb Mon Sep 17 00:00:00 2001 From: Drew Khoury Date: Fri, 19 Nov 2021 10:43:53 -0600 Subject: [PATCH 1/5] updated approvers notes --- README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0eaf474..b7725ef 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,23 @@ For each scenario, please do the following: 1. Create a card on the respective [Trello board](https://trello.com/b/7SvNAROB/kubernetes-training) 1. Work on the scenario, try it out in your own environment `https://www.katacoda.com/$GITHUBHANDLE` 1. When you're satisfied, send in a pull request. -1. Next, get two reviews/thumbs up from team members (@mindfulmonk, @joshuatalb and @andresguisado) +1. Next, get two reviews/thumbs up from approvers 1. Once your scenario has been reviewed, we will merge it and it will appear on https://katacoda.com/contino +## Approvers + +- Marcus Maxwell - @mindfulmonk +- Jaroslav Pantsjoha - @joshuatalb +- Andres Guisado - @andresguisado (contino alumni) +- Andrew Khoury - @drewkhoury +- Craig Kilpatrick - @ckilpatrick20 + +**How to approve / what to look for:** + +Approvers should review the module as a second set of eyes to ensure it flows well (no issues when walking through the course). + +Approvers should also check that content is approriate for Contino branding, given these are public. + ## Resources View the [Katacoda documentation](https://www.katacoda.com/docs) for information on how to edit environments, scenarios and more. From 6df4600cb1ff229fb5d6f3abc38c2b5c8f3c26fe Mon Sep 17 00:00:00 2001 From: Drew Khoury Date: Fri, 19 Nov 2021 10:45:47 -0600 Subject: [PATCH 2/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b7725ef..2617cdf 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ For each scenario, please do the following: ## Approvers - Marcus Maxwell - @mindfulmonk -- Jaroslav Pantsjoha - @joshuatalb +- Jaroslav Pantsjoha - @jpantsjoha - Andres Guisado - @andresguisado (contino alumni) - Andrew Khoury - @drewkhoury - Craig Kilpatrick - @ckilpatrick20 From 81addcb2b233fd43ebc05958dc19b4f2d9c91a89 Mon Sep 17 00:00:00 2001 From: Drew Khoury Date: Fri, 19 Nov 2021 12:51:56 -0600 Subject: [PATCH 3/5] adding contribution info adding contribution info --- contributions.md | 200 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 contributions.md diff --git a/contributions.md b/contributions.md new file mode 100644 index 0000000..07b6f7f --- /dev/null +++ b/contributions.md @@ -0,0 +1,200 @@ +# How to setup your own Katacoda pipeline + +Make sure you create a katacoda account that's linked to your own repo which is a fork of the contino repo. Here why: + +- You have full control over all your changes +- You can deploy and then test your changes +- You can use/deliver training if you have an immediate need +- You can inlcude a link to the working scenario in your PR for review +- There's no other way to deploy/test changes without forking and using your own repo +- Merging back in is clean + +**eg: Drew's Contino** KataCoda Profile: https://www.katacoda.com/drewkhoury-contino + +- Login: Google Account Andrew.khoury@contino.io +- Repo: https://github.com/drewkhoury/katacoda-scenarios-1 (fork of: https://github.com/contino/katacoda-scenarios) + +## What if you want to work on your own Katacoda modules independent from Contino? + +If you'd like to test katacoda lessons that aren't contino based, or have multiple deployments at once, having independent accounts and github repos is essential (and easy). + +You can use a variety of Google, Github and Email accounts for this. eg: + +**Drew's Sandbox/Personal:** KataCoda Profile: https://www.katacoda.com/drewkhoury +- Login: GitHub drew.khoury@gmail.com (or I could have used Google Account drew.khoury@gmail.com) +- Repo: https://github.com/drewkhoury/katacoda-drewkhoury + + +# Deployments + +Useful dashboard links to verify that deployments were successful: + +- https://dashboard.katacoda.com/content/ +- https://dashboard.katacoda.com/content/testruns/ +- https://dashboard.katacoda.com/content/debug/ + +It can take 1 minute, or 20 minutes for deployed courses to show up on your profile. + +You can inspect the page and look for "gitCommit" to verify what deployment you're seeing, eg: `` + +## Viewing your own lesson / debug + +When viewing your own lesson you can access debug from the "SCENARIO AUTHORING INFORMATION" link at the top of the page. + +e.g: if your background script is downloading software through apt it might look like this: + +``` +Warning: Permanently added 'host01,172.17.0.12' (ECDSA) to the list of known hosts. WARNING: apt does not have a stable CLI interface. Use with caution in scripts. Reading package lists... Building dependency tree... Reading state information... The following packages were automatically installed and are no longer required: libc-ares2 libnetplan0 nodejs-doc python3-netifaces Use 'apt autoremove' to remove them. The following additional packages will be installed: ant ant-optional antlr bnd groovy ivy java-wrappers junit4 libantlr-java �� libasm-java libbcel-java libbcpg-java libbcprov-java libbindex-java libbsf-java libbsh-java libcommons-codec-java libcommons-collections3-java � libcommons-compress-java libcommons-lang-java libcommons-logging-java lib +``` + +# Tips + +View the [Katacoda documentation](https://www.katacoda.com/docs) for information on how to edit environments, scenarios and more. [scenario-examples](https://github.com/katacoda/scenario-examples) github. + +## Courses + +[Courses](https://www.katacoda.community/essentials/git-repository-structure.html#courses) - each `*-pathway.json` in the parent directory creates a course, which can point to a collection of scenarios. + +The scenarios can be grouped by a common subject, and this is represented with a course. A Katacoda course is defined by creating a pathway file. The pathway defines which scenarios should be included in the course and the order to display them. + +## Basic Katacoda Syntax in markdown + +### Open a file + +``` +`relative/path/to/file.foo`{{open}} +``` + +### Replace file + +``` +
+you
+multi
+line
+content
+
+``` + +### Execute a command + +``` +`your command`{{execute}} +``` + +### Displaying a Progress Spinner / Wait Script + +Example from katacoda: [scenario-examples/displaying-progress-spinner](https://github.com/katacoda/scenario-examples/tree/main/displaying-progress-spinner) + +In [foreground.sh](https://github.com/katacoda/scenario-examples/blob/main/displaying-progress-spinner/foreground.sh) they use a `sleep 1` however that could fail (might take a few seconds to load the foreground script). Use this instead: + +``` +while [ ! -f /usr/local/bin/wait.sh ] +do + sleep 0.2 +done +``` + +Here's an example of how to include the wait script (which needs to be done on the host) alongside other assets in `index.json`: +``` + "assets": { + "client": [{ + "file": "*", + "target": "~/" + }], + "host01": [ + {"file": "wait.sh", "target": "/usr/local/bin/", "chmod": "+x"} + ] + } +``` + +### VS Code Layout + +https://www.katacoda.community/essentials/layouts.html + +At the moment, VS Code integration is only supported in our **Ubuntu based environments** but this is being rolled out across all our environments. + +### Relative path for files when interacting with editor + +You may want to use relative links in your markdown, as well as having a default folder accessable in your IDE. + +Let's assume you have the following folder structure in your repo for `scenario-foo`: `assets/folder/path/to/your/app` then you would set your `uieditorpath` to: + +``` + "environment": { + "uieditorpath": "/root/folder/path/to/your/app" + }, +``` + +Then you can do things like this: + +``` +`relative/path/to/file.foo`{{open}} +``` + +Instead of: + +``` +`/root/folder/path/to/your/app/relative/path/to/file.foo`{{open}} +``` + +### Sample `index.json` + +This is an example of an `index.json` skeleton. + +Files that need to live in the root of the lesson repo (alongside `index.json`): + +- steps/intro/finish: `*.md` +- courseData: `background.sh` (katacoda runs this script you specify in the background on lesson-start) +- code: `foreground.sh` (katacoda runs this script you specify in the forground on lesson-start) + +Files that need to live in the `assets/` folder in the lesson repo: + +- `wait.sh` this needs to be available in the terminal (if you want to support progress spinner feature), so we include it in `assets/` and copy it to `host01` +- anything else we need available for our lesson, in our example we have `assets/folder/path/to/your/app` which contains our application + + ``` + { + "title": "My Senario", + "description": "My Senario", + "difficulty": "Beginner", + "time": "30 minutes", + "icon": "fa-java", + "details": { + "steps": [ + { + "title": "Step 1", + "text": "step1.md" + }, + { + "title": "Step 2", + "text": "step2.md" + } + ], + "intro": { + "text": "intro.md", + "courseData": "background.sh", + "code": "foreground.sh" + }, + "finish": { + "text": "finish.md" + }, + "assets": { + "client": [{ + "file": "*", + "target": "~/" + }], + "host01": [ + {"file": "wait.sh", "target": "/usr/local/bin/", "chmod": "+x"} + ] + } + }, + "environment": { + "uieditorpath": "/root/folder/path/to/your/app", + "uilayout": "vscode-terminal-split" + }, + "backend": { + "imageid": "ubuntu:2004" + } +} + ``` From c693fdc0561cfe57fc4fb593377dbd52421f3c40 Mon Sep 17 00:00:00 2001 From: Drew Khoury Date: Fri, 19 Nov 2021 12:56:06 -0600 Subject: [PATCH 4/5] Update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2617cdf..5d6952d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # Contino learning on Katacoda -This repo stores the code for the [Katacoda scenarios](https://katacoda.com/contino/) which we're currently using to run our Kubernetes training. - -Each `.json` in the parent directory creates a course, which scenarios belong to. +This repo stores the code for the [Katacoda scenarios](https://katacoda.com/contino/) which we're currently using to run Contino branded training that's available to the public. ## Contributions @@ -16,6 +14,8 @@ For each scenario, please do the following: 1. Next, get two reviews/thumbs up from approvers 1. Once your scenario has been reviewed, we will merge it and it will appear on https://katacoda.com/contino +See [contributions.md](contributions.md) for more details, and tips when authoring katacoda lessons. + ## Approvers - Marcus Maxwell - @mindfulmonk From 199d6d8c5b167eac50726770d94f410c0ab87f88 Mon Sep 17 00:00:00 2001 From: Drew Khoury Date: Fri, 19 Nov 2021 13:35:18 -0600 Subject: [PATCH 5/5] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 5d6952d..231f844 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ For each scenario, please do the following: See [contributions.md](contributions.md) for more details, and tips when authoring katacoda lessons. +Be part of the Katacoda slack community at Contino [#practice-katacoda](https://contino.slack.com/archives/C014PLJFBS7). + ## Approvers - Marcus Maxwell - @mindfulmonk