Setup you learning and development environment¶
The automation used within the toolkit uses a number of open source tools and utilities. To avoid issues with different operating systems, command line interpreters (shells) and versions of the various tools, it is recommended that a container or virtual machine is used, so you will have a verified working environment for the automation to run in.
Some of the tools used are:
Todo
what about other cloud CLIs?
Supported runtime environments¶
The developers do not have the bandwidth to run and test will all possible combinations of runtimes across different operating systems, so these are the recommended, tested OS/runtime environments:
- Windows Subsystem for Linux running Ubuntu 22.04.1 LTS image with Docker Engine installed
Docker¶
Docker Desktop provides a container environment for MacOS. It is free to use for non-commercial uses, but requires a license for commercial use.
If the license isn't an issue then this is the simplest, recommended option to use.
If running on Linux or Windows Subsystem for Linux, then docker engine is the recommended option to use.
Multipass¶
Multipass is a free virtual machine environment for Windows, MacOS and Linux to run Ubuntu images. Only Multipass on MacOS is supported within this documentation.
Warning
Some users have reported DNS resolution issues when using Multipass with some VPN clients, such as Cisco Anywhere. There are workaround solutions covered in the setup tutorial.
Additional unsupported options¶
There are some additional environments that are used within the community, but these are not supported and cannot be guaranteed to work. There are also some known issues with the environments listed below:
Podman¶
Podman is an open source tool, free to use, that provides much the same functionality as Docker Desktop. There are some known issues with Podman:
-
When resuming from suspend, if the podman machine is left running, it will not automatically synchronize to the host clock. This will cause the podman machine to lose time. Either stop/restart the podman machine or define an alias like this in your startup scripts:
alias fpt="podman machine ssh \"sudo chronyc -m 'burst 4/4' makestep; date -u\""
then fix podman time with the
fpt
command. -
There is currently an QEMU bug which prevents binary files that should be executable by the podman machine vm from operating from inside a mounted volume path. This is most common when using the host automation directory, vs a container volume like
/workspaces
for running the automation. Generally the cli-tools image will have any binary needed and theutils-cli
module will symbolically link, vs. download a new binary into this path. However there can be drift between binaries incli-tools
image used bylaunch.sh
and those requested to theutils-cli
module.
Colima¶
Colima is an open source container engine for Intel or Arm based Mac systems. It is free to use, but there are some known issues with Colima:
- Network/DNS failures under load
- Read/write permissions to local storage volumes
- Issues running binary executables from volumes mounted from the host
Setup instructions¶
Instructions for setting up your chosen container or VM environment are covered in the first tutorial