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
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
Directory
Creates a directory.
Same as with files path is not expanded, so ~ and environment variables will not be replaced with corresponding values
- type: directory
path: /home/devzero/src/
permissions: "0755" # Optional, can also be formated as "rwxr-x---", 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.