From 103eb7c35ff9702185f0e29e8573c053b4ebddbc Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Tue, 25 Jun 2024 11:07:17 +0100 Subject: [PATCH 1/8] docs: further guidelines around adding extra scripts and assets --- README.md | 2 ++ docs/transformer.md | 29 ++++++++++++++++++++++++++++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d6f24db..814209e 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,8 @@ We welcome contributions to enhance these tutorials. ### Propose changes +> **Note:** Follow the below contribution steps if you plan to create a tutorial that is independant from the offical Grafana Labs documentation. Otherwise follow these [steps](./docs/transformer.md#generate-a-tutorial). + 1. Fork the repository by clicking on the **Fork** button on the top right corner of this page. For more information, refer to [Fork a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). diff --git a/docs/transformer.md b/docs/transformer.md index c626569..7bd40bb 100644 --- a/docs/transformer.md +++ b/docs/transformer.md @@ -11,7 +11,7 @@ The tool uses the metadata to perform preprocessing on the source file and gener | Field | Type | Description | | ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | -| `killercoda.backend.imageid` | String | The name of the Killercoda environment's backend image. Supported values include `ubuntu`. | +| `killercoda.backend.imageid` | String | The name of the Killercoda environment's backend image. Supported values include, `ubuntu`, `ubuntu-4GB` `kubernetes-kubeadm-1node`, `kubernetes-kubeadm-2nodes`| | `killercoda.description` | String | The description displayed on the Killercoda website | | `killercoda.details.finish.text` | String | The filename of the finish page Markdown source in the grafana/killercoda repository. | | `killercoda.details.intro.text` | String | The filename of the introduction page Markdown source in the grafana/killercoda repository. | @@ -333,3 +333,30 @@ To generate a tutorial: 1. In each repository, commit your changes, push your branch, and open a pull request. 1. A Killercoda maintainer reviews the PR to ensure that the generate tutorial works as expected. + + +## Scripts and Extra Course Files + +If your tutorial requires scripts or extra files, make sure to manually add them to the tutorial directory in the Killercoda repository. For example, if your tutorial requires a script to run: + +1. Add the bash script to the tutorial directory in the Killercoda repository. See the [what-is-loki](../loki/what-is-loki/) tutorial for an example. +2. Add the script to the `scripts` field in the `index.json` file: + ```json + "intro": { + "text": "intro.md", + "foreground": "setup.sh" + }, + ``` + +For extra assets, such as images or configuration files: +1. Create a directory called `assets` in the tutorial directory. +2. Add the assets to the `assets` directory. +3. Add the mount path to the `index.json` file: + ```json + "assets": { + "host01": [ + {"file": "/assets", "target": "/assets"} + ] + } + ``` + See the [grafana-basics](../grafana/grafana-basics/index.json) tutorial for an example. \ No newline at end of file From b1dde38880ca96d292eee1323690c259f726812d Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Tue, 25 Jun 2024 11:14:30 +0100 Subject: [PATCH 2/8] Added workflow indicator --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 814209e..d44a200 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,12 @@ # Killercoda - Grafana Labs Tutorials +

+ + Regenerate Tutorials + +

+ + Welcome to the Grafana Labs tutorials repository. This repository contains interactive tutorials for Grafana Labs, hosted on [Killercoda](https://killercoda.com/grafana-labs/). These tutorials aim to help users understand and implement Grafana solutions without the need to download or install the software. From 8e415b7c4e6892d91757dbdcbcf8144e88beb822 Mon Sep 17 00:00:00 2001 From: Jay Clifford <45856600+Jayclifford345@users.noreply.github.com> Date: Tue, 25 Jun 2024 17:19:11 +0100 Subject: [PATCH 3/8] Update README.md Co-authored-by: Jack Baldry --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d44a200..56ff47d 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,9 @@ We welcome contributions to enhance these tutorials. ### Propose changes -> **Note:** Follow the below contribution steps if you plan to create a tutorial that is independant from the offical Grafana Labs documentation. Otherwise follow these [steps](./docs/transformer.md#generate-a-tutorial). +> **Note:** +> Use the following contribution steps if you want to create a tutorial that's not also part of Grafana Labs documentation. +> Otherwise follow these [steps](./docs/transformer.md#generate-a-tutorial) to generate a tutorial from that documentation. 1. Fork the repository by clicking on the **Fork** button on the top right corner of this page. From 9876b4e3ecf9e3317122da65dc82dcd60007a916 Mon Sep 17 00:00:00 2001 From: Jay Clifford <45856600+Jayclifford345@users.noreply.github.com> Date: Tue, 25 Jun 2024 17:19:17 +0100 Subject: [PATCH 4/8] Update docs/transformer.md Co-authored-by: Jack Baldry --- docs/transformer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/transformer.md b/docs/transformer.md index 7bd40bb..c07e0a1 100644 --- a/docs/transformer.md +++ b/docs/transformer.md @@ -339,7 +339,7 @@ To generate a tutorial: If your tutorial requires scripts or extra files, make sure to manually add them to the tutorial directory in the Killercoda repository. For example, if your tutorial requires a script to run: -1. Add the bash script to the tutorial directory in the Killercoda repository. See the [what-is-loki](../loki/what-is-loki/) tutorial for an example. +1. Add the bash script to the tutorial directory in the Killercoda repository. Refer to the [what-is-loki](../loki/what-is-loki/) tutorial for an example. 2. Add the script to the `scripts` field in the `index.json` file: ```json "intro": { From 18b1e4da0dd10863222804910a8e1b256e01fde7 Mon Sep 17 00:00:00 2001 From: Jay Clifford <45856600+Jayclifford345@users.noreply.github.com> Date: Tue, 25 Jun 2024 17:19:44 +0100 Subject: [PATCH 5/8] Update docs/transformer.md Co-authored-by: Jack Baldry --- docs/transformer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/transformer.md b/docs/transformer.md index c07e0a1..82c69a6 100644 --- a/docs/transformer.md +++ b/docs/transformer.md @@ -359,4 +359,4 @@ For extra assets, such as images or configuration files: ] } ``` - See the [grafana-basics](../grafana/grafana-basics/index.json) tutorial for an example. \ No newline at end of file + Refer to the [grafana-basics](../grafana/grafana-basics/index.json) tutorial for an example. \ No newline at end of file From 36f8331ba12522df206dff14ae5f1219f5f72a52 Mon Sep 17 00:00:00 2001 From: Jay Clifford <45856600+Jayclifford345@users.noreply.github.com> Date: Tue, 25 Jun 2024 17:19:53 +0100 Subject: [PATCH 6/8] Update docs/transformer.md Co-authored-by: Jack Baldry --- docs/transformer.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/transformer.md b/docs/transformer.md index 82c69a6..5488d8a 100644 --- a/docs/transformer.md +++ b/docs/transformer.md @@ -334,8 +334,7 @@ To generate a tutorial: 1. A Killercoda maintainer reviews the PR to ensure that the generate tutorial works as expected. - -## Scripts and Extra Course Files +## Scripts and extra course files If your tutorial requires scripts or extra files, make sure to manually add them to the tutorial directory in the Killercoda repository. For example, if your tutorial requires a script to run: From 4b279a9ea12e7ddaac0937f9e23f0c182d7076df Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Wed, 26 Jun 2024 14:17:39 +0100 Subject: [PATCH 7/8] Updated json examples to full --- docs/transformer.md | 51 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 8 deletions(-) diff --git a/docs/transformer.md b/docs/transformer.md index 6d6c2c3..ef634be 100644 --- a/docs/transformer.md +++ b/docs/transformer.md @@ -342,12 +342,31 @@ To generate a tutorial: If your tutorial requires scripts or extra files, make sure to manually add them to the tutorial directory in the Killercoda repository. For example, if your tutorial requires a script to run: 1. Add the bash script to the tutorial directory in the Killercoda repository. Refer to the [what-is-loki](../loki/what-is-loki/) tutorial for an example. -2. Add the script to the `scripts` field in the `index.json` file: +2. Add the script to the desired step within the `index.json` file. Note that `foreground` scripts run in the foreground (seen in terminal), and `background` scripts run in the background (Run in background thread). For example: ```json - "intro": { - "text": "intro.md", - "foreground": "setup.sh" + { + "title": "What is Loki?", + "description": "A sandbox enviroment to introduce Loki to new users.", + "details": { + "intro": { + "text": "intro.md", + "foreground": "script1.sh" + }, + "steps": [ + { + "text": "step1.md", + "foreground": "script2.sh" + } + ], + "finish": { + "text": "finished.md" + } }, + "backend": { + "imageid": "ubuntu" + } + } + ``` For extra assets, such as images or configuration files: @@ -355,10 +374,26 @@ For extra assets, such as images or configuration files: 2. Add the assets to the `assets` directory. 3. Add the mount path to the `index.json` file: ```json - "assets": { - "host01": [ - {"file": "/assets", "target": "/assets"} - ] + { + "title": "Grafana Basics", + "description": "In this demo learn how to install and configure Grafana", + "details": { + "intro": { + "text": "intro.md" + }, + "steps": [], + "finish": { + "text": "finished.md" + }, + "assets": { + "host01": [ + {"file": "*", "target": "/education"} + ] + } + }, + "backend": { + "imageid": "ubuntu" } + } ``` Refer to the [grafana-basics](../grafana/grafana-basics/index.json) tutorial for an example. \ No newline at end of file From 9a0d216823125fef93d0d39016d2cb0fe755c053 Mon Sep 17 00:00:00 2001 From: Jay Clifford <45856600+Jayclifford345@users.noreply.github.com> Date: Wed, 26 Jun 2024 14:51:05 +0100 Subject: [PATCH 8/8] Update docs/transformer.md Co-authored-by: Jack Baldry --- docs/transformer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/transformer.md b/docs/transformer.md index ef634be..4be6bbd 100644 --- a/docs/transformer.md +++ b/docs/transformer.md @@ -342,7 +342,7 @@ To generate a tutorial: If your tutorial requires scripts or extra files, make sure to manually add them to the tutorial directory in the Killercoda repository. For example, if your tutorial requires a script to run: 1. Add the bash script to the tutorial directory in the Killercoda repository. Refer to the [what-is-loki](../loki/what-is-loki/) tutorial for an example. -2. Add the script to the desired step within the `index.json` file. Note that `foreground` scripts run in the foreground (seen in terminal), and `background` scripts run in the background (Run in background thread). For example: +2. Add the script to the desired step within the `index.json` file. Note that `foreground` scripts run in the foreground (seen in terminal), and `background` scripts run in the background (run in background thread). For example: ```json { "title": "What is Loki?",