Build an image

Building an image means booting a VM from an image you already have, changing it, and publishing what you end up with. This page walks through one build from start to finish.

Start a build session

1. In the sidebar, click Building blocks → Images.
2. Click Create image.
3. In Base image, pick what to build on top of. The list is split into System images — Instruqt’s base images — and Team, your own published images. The field is searchable.
4. In Version, pick which snapshot of that base to boot. Latest is the default and follows whatever the base publishes; a specific version always boots the same filesystem.
5. In Machine, pick the processors and memory of the VM you build on. See Machine and disk.
6. In Disk, set the size of the VM’s disk with the slider, or type it in the box beside it. See Machine and disk.
7. Click Start building.

The image’s name and description are not asked for here. Every build starts from an existing image, and what you are building only gets named when you publish it.

To build on top of one of your own published images, you can skip straight to step 4: click New version on the image’s row menu, or on its detail page. The base is already chosen.

The platform then provisions a VM for you. It moves through Starting while the machine boots and the agent connects, and the builder opens once it is running. This usually takes a minute or two.

Machine and disk

The machine sets the build VM’s processors and memory. It only affects the build session; a lab sets its VM’s size with the resources block.

Machine	vCPU	Memory
Small	2	4 GB
Medium (default)	4	8 GB
Large	8	16 GB
Extra large	16	32 GB

Pick a larger machine for builds that compile software, or that run containers or a desktop.

The disk is between 20 GB and 500 GB, and 40 GB by default. The slider moves in steps of 10 GB; type a size in the box for one in between. Unlike the machine, the disk stays with the image: every version you publish from the session carries it, so a lab VM booting that version gets a root filesystem of the same size. A size below the base image’s own disk has no effect, and the VM keeps the base image’s size.

A larger disk does not make the image bigger to download. A published version stores only the data written during the session, not the empty space, so a 500 GB disk with 5 GB of changes pulls as fast as a 40 GB one. The size is still what every lab VM booting the version can fill, so pick what your labs need rather than the maximum.

The root filesystem is grown to fill the disk before the session opens, so the space is there from your first command. That is not possible when:

• the root filesystem is not on a partition (e.g. it is on LVM), or is not the last partition on the disk;
• the root filesystem is not ext2, ext3, ext4, XFS or Btrfs;
• the image lacks the tools to grow it: findmnt, lsblk, and growpart or sfdisk;
• a step of the grow fails.

The build then keeps the root filesystem the base image shipped with, and the session still works. Usually a warning above the work area says how much of the disk the root filesystem uses, and stays until you click Dismiss. The warning names only the LVM and partition cases, and it needs df and lsblk in the image, so on a minimal image it may not appear at all. To check, run df -h / in the Terminal panel and compare the size with the disk you picked.

The builder

The work area has three panels:

• Terminal — a full shell on the VM. Install packages, start services, run scripts, pull down whatever the image needs.
• Editor — a file browser and editor for the VM’s filesystem, for writing config files and dropping files in by hand.
• Display — the VM’s screen. A VM running a desktop shows the desktop; any other VM shows its text console. See The display.

They open stacked as tabs with the terminal in front. Drag a tab to split them into columns or rows; the arrangement is remembered for your next build. The set is fixed — you cannot close a panel or add another.

Everything you do here is happening on a real machine. A package you install is installed, a service you enable is enabled, and all of it is what gets captured when you publish.

An example

# Refresh the package lists and install what the lab needs
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv

# Pre-install the libraries, so lab startup doesn't have to
pip3 install numpy pandas matplotlib jupyter

# Drop the package cache — it only makes the published image bigger
sudo apt-get clean
sudo rm -rf /var/lib/apt/lists/*

The last two lines matter more than they look. Anything left on disk is published with the image, and a smaller image boots faster in every lab that uses it.

The display

The Display panel shows the VM’s screen and takes your mouse and keyboard, for software you can only set up through its own interface (e.g. a graphical installer). The screen is scaled to fit the panel, and a desktop resizes to match it.

While a checkpoint is created or rolled back, the screen is unavailable for a moment. The panel says it is connecting to the build VM’s display, and reconnects on its own when the VM is ready again.

A build has one display. If you open the same build in a second browser window, the newest window takes the display over, and the older one shows This display is open in another window. Click Show it here to take it back.

Copy and paste work both ways when the VM runs a desktop with spice-vdagent, which shares its clipboard with the panel. Install it alongside the desktop if your image doesn’t have it (e.g. sudo apt-get install spice-vdagent). Plain text only:

• Text copied in the VM is put on your computer’s clipboard while the builder’s browser tab has focus.
• Press Ctrl+V or Shift+Insert in the panel to paste your computer’s clipboard into the VM. In a terminal on the VM’s desktop, press Ctrl+Shift+V. Use Ctrl on macOS too. Your browser may ask for permission to read the clipboard the first time.

A text console has no clipboard to share. To paste text into a VM without a desktop, use the Terminal panel.

Checkpoints

A checkpoint is a snapshot of the build VM as it is right now — its filesystem, its installed packages, its running state. Take one before something risky and you can put the machine back.

Checkpoints belong to the session, not to the image. They are not published versions, and they are destroyed with the VM when the session ends.

Click Checkpoints in the builder header to open the rail.

Action	What it does
Create	Snapshots the running VM. You describe what you just changed — that description is the only thing you will have to recognise it by later.
Roll back	Puts the VM back to that checkpoint and reconnects the terminal and display to the restored machine. Everything changed since is discarded and cannot be recovered.
Delete	Removes a checkpoint from the session’s history. The VM keeps the state it is in — you just lose the ability to roll back to that point.

The rail always holds one checkpoint you did not take: Initial state, the machine as it booted. Rolling back to it resets the build to the pristine base image without ending the session, and it cannot be deleted.

Tip

Take a checkpoint before a large install or a system-wide configuration change. Rolling back is near instant; starting the session over is not.

Keep the session alive

A build session runs for two hours from the moment the VM is editable, and is reclaimed after 15 minutes with no activity.

The builder sends a heartbeat while its tab is open, so a session you are working in stays alive on its own. If you leave it idle, a warning appears a few minutes before the session ends, and you can carry on from there.

Neither clock can be extended from the builder. Publish while you still have time — an expired session is destroyed along with every checkpoint in it.

Before you publish

Every lab boots a copy of your image as a new VM, on the lab’s own network, with a different IP address from the build session. Publishing saves the disk as the session left it: the platform stops the VM without shutting down the services running in it. Anything you started while building is saved as it was on the build VM: cluster databases, generated certificates and keys, node identities, and configuration that points at the build session’s IP address. Software that reads this state on boot tries to reach the old address, or presents the same identity in every lab. VMs then get slow or fail to start, often only some of them and only when many start at once.

Publishing already clears the machine ID and SSH host keys and resets cloud-init. It does not touch the state your own software creates.

Install your software and pull its container images in the build session, but don’t initialize or start it there. Either reset its runtime state as the last step before you publish, or leave it uninitialized and start it from the VM’s startup script or a task setup script.

Reset state like this before publishing:

• Kubernetes clusters (e.g. k3s, kubeadm, MicroK8s): the cluster datastore, certificates, and kubeconfig files.
• Other clustered software (e.g. Docker Swarm, Consul, Nomad, Vault, Elasticsearch, Kafka): node IDs, cluster membership, and data directories.
• Generated credentials: TLS certificates and keys, API tokens, and license activations tied to one machine.
• Hardcoded addresses: the build session’s IP address in configuration files or /etc/hosts.

For example, to reset k3s while keeping the container images you pulled:

sudo /usr/local/bin/k3s-killall.sh
sudo rm -rf /var/lib/rancher/k3s/server /etc/rancher/k3s/k3s.yaml

k3s creates a fresh cluster with new certificates on the next boot. If your lab deploys workloads such as Helm charts onto the cluster, deploy them from the startup script or a setup script, not into the image.

Publish

1. Reset any runtime state your session created, then click Publish in the builder header.
2. If the session was built on one of your team’s own images, choose under Publish as whether this is a new version of that image or a new image. Building on an Instruqt base image, or on a protected image, only offers a new image — see Base images.
3. For a new image, enter the Image name. Up to 100 characters, and it has to be free within your team. This becomes team-slug/name, and it cannot be changed later.
4. Enter the Version tag. The field is prefilled by counting up from the image’s newest numeric tag, or v1 if there is nothing to count from.
5. Optionally add a Description — what changed in this version. Up to 500 characters, shown beside the version in the catalog.
6. Click Publish.

Version tag rules

Rule	Detail
Registry tag syntax	Starts with a letter, number or underscore, then letters, numbers, dots, dashes and underscores. Up to 128 characters.
New for this image	A tag the image already has is refused. Publish a new number instead.
latest is reserved	Kept for Instruqt’s managed base images. Give your version a number.
Use a number you can sort	An untagged reference in a lab resolves to the highest version number, so v1, v2, 1.4.2 all work and a word like stable is never picked. See How a reference resolves.

What happens next

Publishing flattens the running VM and pushes it to the registry. That takes minutes rather than seconds, so the dialog does not hold you there: it hands you back to the images list, where a Publishing row in Drafts tracks the push and turns into a catalog entry when it lands — or into a failed row carrying the reason.

The VM is torn down with the publish. To make further changes, start a new session with New version.

Each publish adds a version; the ones already published are untouched. That history is what lets a lab pin an old version and keep working.

Discard

If the build is not worth keeping, click Discard & Exit.

This stops the VM and permanently deletes it, along with every file you changed, every package you installed and every checkpoint from the session. Versions you already published are unaffected. It cannot be undone.

Nothing is written to the catalog, and you can start a new session whenever you like.