How to Install and Use Gremlin Locally with Docker For Mac

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 – Installing Gremlin

After you have created your Gremlin account (sign up here) you will need to find your Gremlin Daemon credentials. Login to the Gremlin App using your Company name and sign-on credentials. These were emailed to you when you signed up to start using Gremlin.

Navigate to Team Settings and click on your Team.

Store your Gremlin client credentials as environment variables, for example:

export GREMLIN_TEAM_ID=3f242793-018a-5ad5-9211-fb958f8dc084
export GREMLIN_TEAM_SECRET=eac3a31b-4a6f-6778-1bdb813a6fdc

Next run the Gremlin Daemon in a Container.

Use docker run to pull the official Gremlin Docker image and run the Gremlin daemon:

$ sudo docker run -d \      --net=host \      --pid=host \      --cap-add=NET_ADMIN \      --cap-add=SYS_BOOT \      --cap-add=SYS_TIME \     --cap-add=KILL \      -e GREMLIN_TEAM_ID="${GREMLIN_TEAM_ID}" \      -e GREMLIN_TEAM_SECRET="${GREMLIN_TEAM_SECRET}" \      -v /var/run/docker.sock:/var/run/docker.sock \      -v /var/log/gremlin:/var/log/gremlin \      -v /var/lib/gremlin:/var/lib/gremlin \    gremlin/gremlin daemon

Use docker ps to see all running Docker containers:

$ sudo docker ps
CONTAINER ID        IMAGE                COMMAND                  CREATED             STATUS              PORTS                    NAMESb281e749ac33        gremlin/gremlin      "/ daem…"   5 seconds ago       Up 4 seconds                                 relaxed_heisenberg

Jump into your Gremlin container with an interactive shell (replace b281e749ac33 with the real ID of your Gremlin container):

$ sudo docker exec -it b281e749ac33 /bin/bash

From within the container, check out the available attack types:

$ gremlin help attack-container
Usage: gremlin attack-container CONTAINER TYPE [type-specific-options]Type "gremlin help attack-container TYPE" for more details:  blackhole # An attack which drops all matching network traffic  cpu   # An attack which consumes CPU resources  io    # An attack which consumes IO resources  latency # An attack which adds latency to all matching network traffic  memory  # An attack which consumes memory  packet_loss # An attack which introduces packet loss to all matching network traffic    shutdown  # An attack which forces the target to shutdown  dns   # An attack which blocks access to DNS servers  time_travel # An attack which changes the system time.  disk    # An attack which consumes disk resources  process_killer  # An attack which kills the specified process

Step 3.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 4.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. See how you can harness chaos to build resilient systems by requesting a demo of Gremlin.

Request a Demo