https://github.com/kong/gojira
Multi-purpose tool to ease development and testing of Kong by using Docker containers
https://github.com/kong/gojira
Last synced: 2 months ago
JSON representation
Multi-purpose tool to ease development and testing of Kong by using Docker containers
- Host: GitHub
- URL: https://github.com/kong/gojira
- Owner: Kong
- License: apache-2.0
- Created: 2020-08-24T12:36:31.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-11-07T11:21:12.000Z (almost 2 years ago)
- Last Synced: 2025-05-08T22:07:11.790Z (5 months ago)
- Language: Shell
- Homepage:
- Size: 313 KB
- Stars: 46
- Watchers: 27
- Forks: 23
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
```
_,-}}-._
/\ } /\
_|(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](https://docs.docker.com/compose/compose-file/compose-file-v3/).
```bash
$ 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.
```bash
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.
```bash
$ brew install bash
```
> Homebrew will symlink bash into `/usr/local/bin`.
```bash
$ /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
```
Make sure your `$PATH` gives higher precendence to the upgraded bash.
```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.
```bash
$ 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](docs/manual.md#getting-started)
* [Usage patterns](docs/manual.md#usage-patterns)
* [From vagrant to gojira](docs/vagrant.md)
## 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](docs/manual.md#using-kong-release-images-with-gojira)
#### GOJIRA_DETECT_LOCAL
> default: `1` (on)
Detects if the current path is a kong repository, providing an automatic `-k`
flag.
[Docs](docs/manual.md#start-a-local-kong)
#### 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](docs/manual.md#start-a-local-kong)
#### GOJIRA_USE_SNAPSHOT
> default: `1` (on)
Try to use an automatic snapshot when available.
[Docs](docs/manual.md#using-snapshots-to-store-the-state-of-a-running-container)
#### 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](docs/manual.md#gojira-magic-dev-mode)
#### 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
```bash
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](docs/manual.md#bind-ports-on-the-host)
#### 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](http://asciiartist.com).