config.yaml¶
config.yaml sits next to index.md. The file is optional. With no file, the catalog and the lab page banner show the directory name, and the machine uses the usual size and the shared disk.
A lab name is the directory name: letters, digits, and hyphens. The name default is reserved.
title¶
The name on the catalog card and in the banner at the top of the lab page. Both use the directory name when this is left out.
description¶
The sentence under the title on the catalog card.
author¶
Who wrote the lab. The lab's page shows it. The catalog list leaves it off.
tags¶
Categories for the lab. Write one name, or a list:
Names are compared without regard to case, and repeated names collapse. The lab's page shows them. The catalog list leaves them off.
services¶
Links in the bar above the lesson. Each entry has a name, a port, and a path.
name is the label. It is required. port is the port on the lab machine, from 1 to 65535. A port can appear once. path is the path on that port. It starts with /. Left out, it is /.
The link opens in a new tab.
env¶
Variables to set in the lab machine when a sitting starts. They are written into that sitting's shell. They are not stored on the disk.
A value that begins with $ is copied from the environment outside the lab. The name after $ has to be a shell variable name. If that variable is missing or empty, the lab does not start.
Any other value is taken as text. That text lives in config.yaml, so a secret does not belong there. Use a $ value for a secret, and store the secret with runlabctl.
The name on the left is a shell variable name: a letter or underscore, then letters, digits, and underscores.
snapshot¶
snapshot: true saves the machine once the pack can log in, and later opens resume that save. Leave the line out to boot from the disk each time.
The login has to be worth saving. If a program should already be running, setup.sh has to arrange that the machine accepts the login only after that program is up. The nginx example does this for nginx.
On your machine, the first trylab open writes the snapshot. On the published site, Build writes it, and Publish waits until it exists.
memory_mib¶
Memory for the machine, in MiB. Left out, or set to 0, the machine gets 1024. The number has to be positive. A change applies the next time the lab opens. It does not need a new disk.
vcpus¶
How many CPUs the machine gets. Left out, or set to 0, the machine gets 2. The number has to be positive. A change applies the next time the lab opens. It does not need a new disk.
disk_gib¶
Size of the lab's disk, in GiB. Left out, the disk is 8 GiB. Set a positive number to choose another size. Changing it means building the disk again.
disk_name¶
Which disk the lab boots. The name uses letters, digits, and hyphens.
Left out, a lab with no setup.sh and no file under data/ uses default, the shared disk. Left out on any other lab, the disk is named after the lab directory. Setting the field to default selects that shared disk.
On your own machine, building a lab whose disk_name names some other disk prints that name and does not write a second copy.
badge_id¶
Leave this out unless you have been given a badge identifier. When a learner finishes a lab that sets it, the site can award that badge.
time_limit¶
How long one sitting lasts. Write a duration such as 5m or 300s. The duration has to be positive.
Left out, the sitting uses the usual length. A published lab is shortened to the length the site allows.
What a rebuild sees¶
Build again when setup.sh, a file under data/, or disk_gib changes, and when you turn a snapshot on. The lesson, the title, the description, services, and environment names are read when the lab opens.