Recipe Instructions

Essential Recipe instructions for configuring workspaces, managing files, installing packages, and cloning repositories.

Available Instructions

Instruction	Description
`command`	Runs shell commands inside the workspace.
`file`	Creates a file with specified content.
`directory`	Creates a directory with specified permissions.
`apt-get`	Installs packages using the `apt-get` package manager.
`git-clone`	Clones a Git repository into the workspace.

A recipe is a definition of a workspace. It consists of a base workspace configuration, and a set of steps to be executed. Let's look at a simple recipe:

version: "3" # This must be set to 3, the latest version of our instruction syntax
build:
  steps:
    - type: command
      command: touch hello

Steps while optional are the core tool that you will use to configure your workspace and prepare it for work. Steps can be executed either during build time or launch time. This is accomplished by placing the steps in the corresponding section:

Build time: Configures the workspace before it starts.
Launch time: Runs commands when the workspace boots up.
Run time: Commands executed interactively by the user.

version: "3"
 
build:
  steps:
    - type: command
      command: touch hello
 
launch:
  steps:
    - type: command
      command: touch hello_launch

Here, hello_launch is created at workspace startup, while hello is created at build time.

Most steps can be moved between the launch and build phases of a recipe. But keep in mind that doing more work during the launch of the container will make your workspace start slower.

Minimize heavy tasks in launch-time steps to avoid slowing down workspace startup.

Recipes support various step types for configuring workspaces. Below are the available step types:

Command

The bread and butter step, pretty much everything you need can be accomplished using this step.

- type: command
  name: dump_env # Optional
  command: env > envdump
  directory: /home/devzero # Optional
  user: devzero # Optional
  shell: /bin/bash -l -o errexit -o nounset -o pipefail {} # Optional, can be any interpreter

You can have multiline commands, for example:

- type: command
  command: |
    echo "Hello"
    echo "World"

File

Creates a file with some content.

Paths are not using shell expansion, so you have to write out /home/devzero/projects rather than ~/projects

- type: file
  path: /etc/devzero/hello
  content: "hello" # Supports secret interpolation discussed further in the docs
  permissions: "0644" # Optional, can also be formated as "rw-r--r--", both formats are good
  user: devzero # Optional
  group: devzero # Optional, defaults to being the same as the user

Apt Get

Installs apt packages.

- type: apt-get
  packages: ["sudo", "tar", "wget"]

The apt-get package manager is specific to Debian-based distributions (Ubuntu, Debian). For other operating systems, use: - yum (CentOS, RHEL) - dnf (Fedora) - apk (Alpine Linux)

Example for Fedora:

- type: dnf
  packages: ["git", "vim"]

We also support an easy way to add extra repositories, for example:

- type: apt-get
  packages: ["docker-ce", "docker-ce-cli", "containerd.io"]
  extra_repositories:
    - key_url: https://download.docker.com/linux/ubuntu/gpg
      repository: https://download.docker.com/linux/ubuntu

Or:

- type: apt-get
  packages: ["python3.13", "python3.13-venv", "libpython3.13-dev"]
  extra_repositories:
    - repository: "ppa:deadsnakes/ppa"

You can also specify components:

- type: apt-get
  packages: ["terraform"]
  extra_repositories:
    - key_url: https://apt.releases.hashicorp.com/gpg
      repository: https://apt.releases.hashicorp.com
      components:
        - main

Git Clone

Clones a git repository.

- type: git-clone
  url: https://github.com/Ignas/nukagit
  branch: main # default - not set
  directory: /home/devzero/projects/nukagit_clone # default - code clone root + name of the repository

Semantics for the directory are explained in git documentation.

There are Advanced Instructions that we will learn about them, next.

Recipe Instructions

Available Instructions

Steps

Command

File

Directory

Apt Get

Git Clone

On this page