hyzone

v0.0.3

Published

2 years ago

Docker local orchestrator, Docker Compose but better

Downloads

0High
0Medium
0Low

jan-swiecki

docker orchstration manager

Hyzone

Docker orchestration for local/CI environment for Linux users. It might be a better alternative to Docker Compose.

It's bash-based but you don't need to know bash to use it if you know basics of *nix based shell. Although bash knowledge gives you more power over hyzone. Additionally you should be quite familiar with Docker.

If you don't understand below example then it is adviced that you familiarize yourself with Linux shell and bash scripting a little bit and/or Docker.

Quick links:

Introduction

Hyzone uses similar concept to docker-compose.yml. Hyzone config file is named hyzone.cfg or hyzone.bash. This file is in bash. It has numerous user-defined functions. Each function can represent either a container or some task to be run (e.g. run multiple containers or check state of the system). Example file:

PROJECT_NAME="myproj"

backend_dockerfile="$(pwd)/backend/Dockerfile"
backend_context="$(pwd)/backend"

backend () {
  docker run -d -v "$(pwd)/backend:/w" -w /w $HYZONE_OPTS node index.js
}

# If we use predefined docker image then just add it after "$HYZONE_OPTS"
frontend () {
  docker run -d -v "$(pwd)/frontend:/w" -w /w $HYZONE_OPTS nginx
}

$HYZONE_OPTS is a variable that hyzone prefills with connection options, image name, labels etc. that are needed for your convenience and for hyzone to operate.

This example is read-only. After this example you'll get other example to play with (see below).

We would run above configuration file with:

$ hyzone run backend
<some docker/hyzone output>

$ hyzone run frontend
<some docker/hyzone output>

Hyzone managed containers are to be treated as ephemeral.

The philosophy of hyzone is to quickly run environment, easily run manual or automatic tests and quickly tear down whole environment on-demand with all images and network removed if needed.

hyzone run <name> will run container in specially created network (named after PROJECT_NAME). All run commands create containers in this network. All containers are available by their function names, e.g. by backend and frontend hostnames within the network.

You can add normal bash functions to hyzone.cfg. hyzone run $1 will run them as normal functions. You can pass arguments to them normally. For example we can have this kind of hyzone.cfg file:

backend () { ...; }
frontend () { ...; }

api_request () {
  hyzone curl backend:8080/api/$1
}

And then

$ hyzone run api_request /version
{
  "version": "1.1.0"
}

When you run hyzone run $1 again then old container will be killed immediately and removed and new one will be rebuilt/recreated. This is why this technology is for development/CI environment.

Hyzone curl

You can run

$ hyzone curl -s "http://backend:8080/api/user/1"
{
  "name": "Jan",
  "status": "Awesome"
}
$ hyzone curl -s "http://frontend/index.html"
<html>
<body>
  This is awesome!
</body>
</html>

Above responses are example responses from backend and frontend apps.

hyzone curl runs curl in special container within same docker network so you can access containers by their hyzone names (i.e. function names). Docker containers in most cases will be named the same as hyzone names.

Random prefix

For CI convenience you can run hyzone generate_random_prefix that will create random prefix and put it in .hyzone_prefix file.

If .hyzone_prefix file is present then created network name and names of all containers are prefixed with this prefix. All logic will work the same and you can use original names from hyzone.cfg - hyzone, even if docker container names are different, can find your containers by labels.

Random prefix is useful if you run mutilple CI pipelines parallely (e.g. for different branches).

hyzone kill and hyzone clean command will work too.

Tips and tricks

hyzone run <name> && hyzone logs <name> -f to run and tail logs immediately. To restart app just CTRL-C and up arrow and re-execute the command. Remember that hyzone run will kill and rebuild and run the container again.

TODO

Update mean-stack example
Create more examples
- Multi-language project example
- Jenkins pipelines examples with selenium and API tests
Finish hyzone with experimental feature.
Allow using other languages in bash functions which is an experimental feature.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme