Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: further guidelines around adding extra scripts and assets #19

Merged
merged 9 commits into from
Jun 26, 2024
Merged

docs: further guidelines around adding extra scripts and assets #19

Changes from 2 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
103eb7c
docs: further guidelines around adding extra scripts and assets
Jayclifford345 Jun 25, 2024
b1dde38
Added workflow indicator
Jayclifford345 Jun 25, 2024
8e415b7
Update README.md
Jayclifford345 Jun 25, 2024
9876b4e
Update docs/transformer.md
Jayclifford345 Jun 25, 2024
18b1e4d
Update docs/transformer.md
Jayclifford345 Jun 25, 2024
36f8331
Update docs/transformer.md
Jayclifford345 Jun 25, 2024
7bec6ca
Merge branch 'staging' into further-docs-improvments
Jayclifford345 Jun 26, 2024
4b279a9
Updated json examples to full
Jayclifford345 Jun 26, 2024
9a0d216
Update docs/transformer.md
Jayclifford345 Jun 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 52 additions & 16 deletions docs/transformer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,15 @@ To use the transformer tool, you need to add Killercoda metadata to the source f
You specify Killercoda tutorial metadata in the source file front matter as the value for the `killercoda` field.
The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial.

| Field | Type | Description |
| ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `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. |
| `killercoda.preprocessing.substitutions` | Array | Substitute matches of a regular expression with a replacement. For more information, refer to [Substitutions](#substitutions). |
| `killercoda.title` | String | The title for the tutorial on the Killercoda website. |
| Field | Type | Description |
| ---------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `killercoda.backend.imageid` | String | The name of the Killercoda environment's backend image. Supported values include `ubuntu`. |
| `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. A [finish directive](#finish) in the documentation source overrides this. |
| `killercoda.details.intro.text` | String | The filename of the introduction page Markdown source in the grafana/killercoda repository. An [intro directive](#intro) in the documentation source overrides this. |
| `killercoda.preprocessing.substitutions` | Array | Substitute matches of a regular expression with a replacement. For more information, refer to [Substitutions](#substitutions). |
| `killercoda.title` | String | The title for the tutorial on the Killercoda website. |


The following YAML demonstrates a number of the fields:

Expand Down Expand Up @@ -341,23 +342,58 @@ 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:
Jayclifford345 marked this conversation as resolved.
Show resolved Hide resolved
```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:
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"}
]
{
"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.
Loading