_,-}}-._
                           /\   }  /\
                          _|(O\_ _/O)
                        _|/  (__''__)
                      _|\/    WVVVVW    tasty vagrant!
                     \ _\     \MMMM/_
                   _|\_\     _ '---; \_
              /\   \ _\/      \_   /   \
             / (    _\/     \   \  |'VVV
            (  '-,._\_.(      'VVV /
             \         /   _) /   _)
              '....--''\__vvv)\__vvv)      ldb

                      Gojira (Godzilla)

gojira

Gojira is a multi-purpose tool to ease the development and testing of Kong by using Docker containers. Very similar to a Vagrant environment, but completely unlike it.

It comes from far away to put an end to vagrant up, vagrant destroy and vagrant wait ten hours.

Spin up as many Kong instances as you want. On different commits at the same time. With different OpenSSL, OpenResty and LuaRocks versions. Run a shell inside of the containers, make Kong roar. Make Kong fail, cd into the repo, fix it. Make Kong start again. Commit it. Push it, ship it!

Synopsis

Usage: gojira action [options...]

Options:
  -t,  --tag            git tag to mount kong on (default: master)
  -p,  --prefix         prefix to use for namespacing
  -k,  --kong           PATH for a kong folder, will ignore tag
  -n,  --network        use network with provided name
  -r,  --repo           repo to clone kong from
  -pp, --port           expose a port for a kong container
  -v,  --volume         add a volume to kong container
  -e,  --env KEY=VAL    add environment variable binding to kong container
  --env-file .env        read a local environment file and bind the variables to the kong container
  --image               image to use for kong
  --cassandra           use cassandra
  --alone               do not spin up any db
  --redis-cluster       run redis in cluster mode
  --host                specify hostname for kong container
  --git-https           use https to clone repos
  --egg FILE            add a docker-compose configuration file to use
  --network-mode        set docker network mode
  --yml FILE            kong yml file
  --apt-mirror DOMAIN   use customized Ubuntu apt mirror (such as --apt-mirror apt-mirror.example.com)
  -V,  --verbose        echo every command that gets executed
  -h,  --help           display this help

Commands:
  up            start a kong. if no -k path is specified, it will download
                kong on $GOJIRA_KONGS folder and checkouts the -t tag.
                also fires up a postgres database .with it. for free.

  down          bring down the docker-compose thingie running in -t tag.
                remove it, nuke it from space. something went wrong, and you
                want a clear start or a less buggy tool to use.

  build         build a docker image with the specified VERSIONS

  run           run a command on a running kong container.
                Use with --cluster to run the command across all kong nodes.
                Use with --index 4 to run the command on node #4.

  run@s[:i]     run a command on a specified service (node i)
                example: 'gojira run@db psql -U kong'

  shell         get a shell on a running kong container.

  shell@s[:i]   get a shell on a specified service s (node i)
                example: 'gojira shell@db'

  port          get allocated random port for kong
  port@s[:i]    or for a specified service s (node i)
                example: 'gojira port 8000'
                         'gojira port@kong:3 8000'
                         'gojira port@redis 6379'

  watch         watch a file or a pattern for changes and run an action on the
                target container
                example: 'gojira watch kong.yml "kong reload"'
                         'gojira watch "* **/**/*"  "kong reload"'

  cd            cd into a kong prefix repo

  image         show current gojira image

  images        list gojira images

  ps            list running prefixes

  ls            list stored prefixes in $GOJIRA_KONGS

  lay           create docker-compose file to use with --egg

  snapshot[?!]  make a snapshot of a running gojira

  compose       alias for docker-compose, try: gojira compose help

  roar          print a decorated dinosaur

  logs          follow container logs

  prefix        show prefix for selected gojira

  nuke [-f]     remove all running gojiras. -f for removing all files

  version       show gojira's version number

Installation

gojira depends on bash, git, docker and docker-compose. Make sure your docker setup is compatible with compose file v3.5.

$ git clone https://github.com/Kong/gojira.git
$ mkdir -p ~/.local/bin
$ ln -s $(realpath gojira/gojira.sh) ~/.local/bin/gojira

Note you need ~/.local/bin on your $PATH. Add them to ~/.profile, .zshrc, ~/.bashrc or ~/.bash_profile depending on which shell you use.

export PATH=~/.local/bin:$PATH

Additional OSX dependencies

GNU core utilities

$ brew install coreutils

Bash > 3

OSX ships with old Bash versions. It's recommended to upgrade bash to an up-to-date version of Bash.

$ brew install bash

Homebrew will symlink bash into /usr/local/bin.

$ /bin/bash --version
GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin19)
Copyright (C) 2007 Free Software Foundation, Inc.
$ /usr/local/bin/bash --version
GNU bash, version 5.1.4(1)-release (x86_64-apple-darwin19.6.0)
Copyright (C) 2020 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

Make sure your $PATH gives higher precendence to the upgraded bash.

$ where bash
/usr/local/bin/bash
/bin/bash
$ bash --version
GNU bash, version 5.1.4(1)-release (x86_64-apple-darwin19.6.0)

If that's not the case, there are many ways of making sure /usr/local/bin/bash takes precedence over /bin/bash. If unsure, the following should work without unintended side effects, assuming your $PATH contains ~/.local/bin on the leftmost (highest) position.

$ export PATH=~/.local/bin:$PATH
$ ln -s $(realpath /usr/local/bin/bash) ~/.local/bin/bash
$ bash --version
GNU bash, version 5.1.4(1)-release (x86_64-apple-darwin19.6.0)

Usage

• Getting started
• Usage patterns
• From vagrant to gojira

Environment variables

Certain behaviours of gojira can be influenced by setting the following environment variables.

Repository related

A number of variables exist that determine how gojira constructs the URL of the Git repository that it clones Kong from.

GOJIRA_REPO

default: kong

Default repository name.

GOJIRA_GIT_HTTPS

default: 0 (off)

Use https instead of ssh for cloning GOJIRA_REPO.

GOJIRA_GIT_HTTPS_REMOTE

Default: 'https://github.com/kong'

Base URL to use for repository if GOJIRA_GIT_HTTPS is 1.

GOJIRA_KONG_REPO_URL

Default: not set

If this environment variable is set, it disables the use of the GOJIRA_REPO, GOJIRA_GIT_HTTPS and GOJIRA_GIT_HTTPS_REMOTE environment variables and instead uses this URL.

Other environment variables

GOJIRA_TAG

default: master

Default tag to clone from GOJIRA_REPO when no -t has been provided

GOJIRA_KONGS

default: ~/.gojira/kongs

Path where prefixes are stored

GOJIRA_HOME

default: ~/.gojira/home

Path to the shared home between gojiras

GOJIRA_IMAGE

Instead of building a development image, force this image to be used. Docs

GOJIRA_DETECT_LOCAL

default: 1 (on)

Detects if the current path is a kong repository, providing an automatic -k flag. Docs

GOJIRA_PIN_LOCAL_TAG

default: 1 (on)

When using a local path (-k or auto), it will always generate the same gojira prefix based on the md5 of the path. Docs

GOJIRA_USE_SNAPSHOT

default: 1 (on)

Try to use an automatic snapshot when available. Docs

GOJIRA_MAGIC_DEV

default: 0 (off)

Runs make dev on up when the environment needs it.

Together with GOJIRA_USE_SNAPSHOT, it will record a snapshot after so the next up can re-use that snapshot. On luarocks change, it will bring up a compatible base, and run 'make dev' again, which should be faster since it will be incremental, but will not record a snapshot to reduce disk usage. Docs

GOJIRA_KONG_PATH

Set this to a full kong path so gojira always references it no matter what This effectively hardcodes all the gojira magic to always, always use this path, without having to reference it by -k. ie

export GOJIRA_KONG_PATH=full/path/to/some/kong

GOJIRA_NETWORK_MODE

default: (empty)

Use network_mode to spin up containers. When no network mode is set, it will use docker's default (bridge), see https://docs.docker.com/network/#network-drivers for available modes. Docs

LUAROCKS

default: the value of RESTY_LUAROCKS_VERSION defined in .requirements file

Use the provided LuaRocks version instead the one from the .requirements file.

Example: LUAROCKS=x.x.x gojira up

Credits

• gojira artwork by ascii artist ldb.