Project Structure

There is a lot of flexibility in how you can structure your lab configuration. One structure that we have found to work well is shown below.

This structure groups artifacts into manageable chunks and provides a clear structure of where files should live. In the example structure below we have separated resources into multiple .hcl files, mostly due to the amount of content in each of those files. If your labs are small, we recommend not splitting up the files too quickly, but chosing consistant names for them when splitting.

├── instructions
│   ├── first_chapter
│   │   ├── first_page.md
│   │   └── second_page.md
│   └── second_chapter
│       └── another_page.md
├── scripts
│   └── first_chapter
│       ├── first_task
│       │   ├── first_check
│       │   ├── my_solve
│       │   └── second_check
│       └── second_task
│           ├── my_solve.sh
│           └── my_check.sh
├── assets
│   ├── image.png
│   └── subdirectory
│       └── image.png
├── notes
│   └── my_note.md
├── files
│   ├── some_config.json
│   └── something.yaml
├── modules
│   └── layouts
│       ├── complex.hcl
│       └── minimal.hcl
├── lab.hcl
├── chapters.hcl
├── tabs.hcl
├── sandbox.hcl
├── tasks.hcl
├── quizzes.hcl
├── modules.hcl
└── variables.hcl

Directories

In the example project structure we have chosen to follow certain standards when placing our files. This structure follows the best practises we have found while creating content, but it is possible to deviate from the naming conventions above.

Instructions

The instructions directory holds all the written content of your lab. The instructions are separated by chapter which contains each of the pages as a separate markdown file.

Scripts

The lifecycle scripts of the tasks are contained in the scripts directory. We have separated by task name, and the scripts themselves can be named anything as they are referenced by path inside of the configuration.

Assets

Any assets that you want to use within the instructions should live in the assets directory. This has the benefit that they are automatically served from the sandbox itself, and can be referenced as e.g. /assets/subdirectory/image.png.

Notes

If you have note tabs defined, the content of those notes should be placed in the notes directory as a separate markdown file for each note.

Files

If your sandbox needs to use a configuration file, template, or any other arbitrary file, these can be placed in the files directory.

Modules

It is a good idea to keep any nested modules inside of the modules directory so they do not clutter the root directory of the project.