How to Install and Use Gremlin Locally with Docker For Mac

This installation guide will walk you through running Gremlin locally using Docker for Mac. You will also run a shutdown attack against an Nginx container.


Step 1.0 – Install Docker For Mac

First you will need to install Docker For Mac if you do not yet have it on your local computer, follow the instructions provided by Docker.

Step 2.0 – Set up your Gremlin credentials

After you have created your Gremlin account (sign up here) you will need to get your Gremlin Daemon credentials. Login to the Gremlin App using your Company name and sign-on credentials. These details were emailed to you when you signed up to start using Gremlin. Navigate to Company Teams Settings and click on your Team. Click the blue Download button to get your Team Certificate. The downloaded contains both a public-key certificate and a matching private key.

Unzip the and set your environment variables as below:

export GREMLIN_TEAM_ID=your_team_id
export GREMLIN_TEAM_CERTIFICATE_OR_FILE="$(cat /path/to/team-client.pub_cert.pem)"
export GREMLIN_TEAM_PRIVATE_KEY_OR_FILE="$(cat /path/to/team-client.priv_key.pem)"

The Gremlin daemon (gremlind) connects to the Gremlin backend and waits for attack orders from you. When it receives attack orders, it uses the CLI (gremlin) to run the attack.

Step 3.0 – Create a Gremlin Docker container

Use docker pull to pull the official Gremlin Docker image:

$ docker pull gremlin/gremlin

Step 4.0 – Create an NGINX container to attack

First we will create a directory for the html page we will serve using nginx:

$ mkdir -p ~/docker-nginx/html
$ cd ~/docker-nginx/html

Create a simple HTML page:

$ vim index.html

Paste in this content:

        <title>Docker nginx tutorial</title>
        <link rel="stylesheet" href="" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
        <div class="container">
            <h1>Hello it is your container speaking</h1>
            <p>This nginx page was created by your Docker container.</p>
            <p>Now it's time to create a Gremlin attack.</p>

Create a container using the nginx Docker image:

$ sudo docker run -l service=nginx --name docker-nginx -p 80:80 -d -v ~/docker-nginx/html:/usr/share/nginx/html nginx

Make sure the docker-nginx container is running:

$ sudo docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                NAMES
7167cacb2536        gremlin/gremlin     "/ daem…"   40 seconds ago      Up 39 seconds                            practical_benz
fb58b77e5ef8        nginx               "nginx -g 'daemon of…"   10 minutes ago      Up 10 minutes>80/tcp   docker-nginx

Step 5.0 - Run A Gremlin Shutdown Attack

Now use the Gremlin CLI (gremlin) to run a Shutdown attack from within a Gremlin container:

sudo docker run -i     --cap-add=NET_ADMIN     -e GREMLIN_TEAM_ID="${GREMLIN_TEAM_ID}"     -e GREMLIN_TEAM_CERTIFICATE_OR_FILE="${GREMLIN_TEAM_CERTIFICATE_OR_FILE}"     -e GREMLIN_TEAM_PRIVATE_KEY_OR_FILE="${GREMLIN_TEAM_PRIVATE_KEY_OR_FILE}"     -v /var/run/docker.sock:/var/run/docker.sock     gremlin/gremlin attack-container docker-nginx shutdown

This attack will shutdown your Nginx container.


You now have Gremlin up and running locally, and you have validated its functionality against a running Nginx container.

Feel free to expand this to other container environments and have fun running Chaos Experiments!

Avoid downtime. Use Gremlin to turn failure into resilience.

Gremlin empowers you to proactively root out failure before it causes downtime. Try Gremlin for free and see how you can harness chaos to build resilient systems.