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

If you want to use the Windows based Envoy images make sure that you switch Docker to use Windows containers.

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 repository

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

git clone git@github.com:envoyproxy/envoy

git clone https://github.com/envoyproxy/envoy.git

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.