Setup the sandbox environment

Before you can run the Envoy sandboxes you will need to set up your environment with Docker and Docker Compose.

You should also clone the Envoy repository with Git

Some of the examples require the installation of additional dependencies.

It is indicated in the sandbox documentation where this is the case.

Tip

If you are working on a Mac OS or Windows system, a simple way to install both Docker and Docker Compose is with Docker Desktop.

Install Docker

Ensure that you have a recent versions of docker installed.

You will need a minimum version of 19.03.0+.

Version 20.10 is well tested, and has the benefit of included compose.

The user account running the examples will need to have permission to use Docker on your system.

Full instructions for installing Docker can be found on the Docker website

Install docker compose

The examples use Docker compose configuration version 3.8.

You will need to a fairly recent version of Docker Compose.

Note

Any 20.0+ version of Docker provides a builtin docker compose command.

The sandboxes are tested using compose in this way, so this is preferable over using the python version.

See Docker compose installation documenation for more information.

Docker Compose (docker-compose) can also be installed as a python application and can be installed through a variety of methods including pip and native operating system installation.

Most of the sandboxes should also work using docker-compose.

Install Git

The Envoy project is managed using Git.

You can find instructions for installing Git on various operating systems here.

Clone the Envoy examples repository

If you have not cloned the Envoy examples repository already, clone it with:

git clone git@github.com:envoyproxy/examples

Additional dependencies

The following utilities are used in only some of the sandbox examples, and installation is therefore optional.

curl

Many of the examples use the curl utility to make HTTP requests.

Instructions for installing curl on many platforms and operating systems can be found on the curl website.

envsubst

Some of the examples require the envsubst command to interpolate environment variables in templates.

The command is a part of the GNU ‘gettext’ package, and is available through most package managers.

jq

The jq tool is very useful for parsing json data, whether it be HTTP response data, logs or statistics.

Instructions for installing jq on many platforms and operating systems can be found on the jq website.

mkpasswd

Some of the examples require the mkpasswd command to generate ~random tokens.

The command is a part of the ‘whois’ package, and is available through most package managers.

netcat

Binary distributions of Netcat are available for Mac OS with brew and in most flavours of Linux.

Ncat is integrated with Nmap and is available in the standard Nmap download packages (including source code and Linux, Windows, and Mac binaries) available from the Nmap download page.

openssl

OpenSSL is a robust, commercial-grade, and full-featured toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols.

Binary distributions of OpenSSL are available for Mac OS with brew and in most if not all flavours of Linux.

Windows users can either use an unofficial binary or compile from source.

Check for installation instructions specific to your operating system.