Introduction

This repository aims to give a tool to facilitate the generation of a new environment for your project each time you need it.

For that it relies on Docker Compose. Target is to have a new directory with a new environment for your project each time you need to. For an example a developer team needs to create a new environment for each ticket. This tool simplify the creation.

It's like having a real library containing services you need to make a specific environment. And it will compose the docker-compose.yml for you.

Even if it facilitates this docker-compose.yml file generation, it doesn't do anything!

You need to describe each service. Each one have its specific directory. Then you create a configuration file to list which services you need.

Finnaly you use the base command to generate your environment in few minutes.

This tool is mainly used for application developers so that they can create a new working environment for each ticket, for every developer, for each project.

Take a tour in configs.example and services.example directories.

Features

• Automatic Docker container creation linked to each other
• docker-compose.yml file generation from standardized folders
• Automatic download of git repositories for targeted projects
• Using config files to describe the "dependencies" of a project (config)
• config files can use inheritance from one to another
• Use portainer as instances management (under "Stack" overview)
• Possible choice of a stack name for each "project" (config) being launched
• Project installation displayed in color (config)
• Using environment variables to overload the application settings
• Podman, Docker and Podman-Compose/Docker-Compose detection
• instances listing (those generated by the program)
• Possible removal/cleaning of a given instance
• System of triggers (hook) to allow to execute a specific code before/after launching containers
• Possible overload of files recovered by Git to overwrite some files or bring additional configuration
• Possibility to use the script on Gitlab Pages to allow it to self-load a repository and deploy the rest of the libraries needed

Prerequisites

You need the following tools:

• Use it under GNU/Linux or an environment using Bash interpreter
• Docker
• Docker Compose

Preparation

First, get the full repository.

Then make the main script executable:

chmod +x genese

Configuration

It is strongly advised to create a .env file from env.example one.

cp env.example .env

This .env file will contain the application configuration, including the location of the directory containing the configs and directory containing the services.

Usage

From the begining, the base command display an help:

bash genese

Available options:

• -h, --help: Display context help
• -i, --instance: List installed instances
• -l, --list: List available configurations
• -n, --name: Name of instance to create. Default: same name as configuration file
• -c <name>, --config <name>: Use the <name> configuration file as a base for deployment
• -d <name>, --delete <name>: Delete given <name> instance

Install and use it in the same command

An interesting little trick to deploy an environment in a single command:

mkdir test
cd test
wget -q -O - "https://raw.githubusercontent.com/blankoworld/genese/develop/genese" |bash -s -- -c default

This command will download the latest version of the software to the test directory and start installing the default configuration.

It is in this way that we can have an interesting tool for installations at once.

Environment variables

On the application

The use of environment variables makes it possible to customize the behavior of the tool.

• POST_DOCKER_HOOK_NAME: Filename for script that will execute some commands after starting all Docker containers. The file should be in one of used services. In example: ./services/postgres14/hook_post_docker.sh. Default value: hook_post_docker.sh.
• FINAL_INSTALLATION_HOOK_NAME: Filname for script that will be executed at the end of installation of an instance. Should be placed in a used service directory. In example: ./services/adminer/hook_fin.sh. Default value: hook_fin.sh.
• PRE_DOCKER_HOOK_NAME: Filname for script executed before Docker containers start. This file should be located in on used service directory. In example: ./services/postgres14/hook_pre_docker.sh. Default value: hook_pre_docker.sh.
• EXTRAS_DIRNAME: Name of the folder containing files you want to be in an instance directory. This folder is in the services for which we want to overwrite some files. Default: extras. Each file and folder in this directory will be in the final destination.
• REPO_FILENAME: Source filename in which you describe branch and repository you need for a given service. Default value: source.
• DOCKER_COMPOSE_FILENAME: final Docker Compose filename for the instance. Default value: docker-compose.yml.
• SERVICE_FILENAME: Filename describing a service (in SERVICES_DIR folder). Default value: compose.yml.
• PORTAINER_NAME: Portainer container name. Used to identify if portainer is launched. Default value: genese_portainer.
• PORTAINER_PORT: Portainer service port. Default value: 4000.
• CONFIG: Default config filename. Default value: default.
• INSTANCES_DIR: Path to the directory where to install the instances generated by the software. Default value: ./instances.
• CONFIGS_DIR: Path to directory that contains configs to use. Default value: ./configs.example.
• SERVICES_DIR: Path to the directory that contains the services to use. Default value: ./services.example.
• DOCKER_SOCKET: Absolute address to Docker socket. Default value: /var/run/docker.sock.

You can overload the values of these variables on the command line, for example:

PORTAINER_PORT=8282 ./genese

Examples of services provided

• ADMINER_PORT: listening port for Adminer service. If not filled in, Docker uses a random available port.

Generated by the application

Some variables are generated by the application, so they cannot be modified at the start of the application.

On the other hand, they can be used in scripts - called hooks - provided by the services.

Here is a non-exhaustive list of available variables:

• MYSERVICE_BRANCH: Replace MYSERVICE with the name of the service you are working on. Enter the name of the branch by which you want to start the instance. Imagine you wanted to use the dev for the adminer service, do : ADMINER_BRANCH="dev" ./genese -c default
• DOCKER_COMPOSE_HEADER_PATH: Path from the template used to start all docker-compose.yml files.
• DOCKER_COMPOSE_FILEPATH: Docker Compose file (docker-compose.yml) absolute path used in a given instance. For example if the instance is in the instance/my_instance folder this means the file is: /absolute/address/instance/my_instance/docker-compose.yml.
• PORTAINER_IMAGE: Docker image used for portainer
• SERVICES_LIST: table with list of services found in choosen user configuration.
• INSTANCE_NAME: instance name (by default the value is those from the config name choosed by user. Except if user gave a specific name)
• CONFIG: config. name choosen by user
• PROGRAM: Application name. By default: genese
• BASE_DIR: absolute path for base directory in which genese is.
• INSTALL_DIR: absolute path in which all instances would be installed. In example in instance/default/ folder.
• TEMPLATES_DIR: path where templates are. In example header.yml (for docker-compose.yml header) would be in it.
• SOURCE: initial repository where genese application is.

CHANGELOG.md file

A CHANGELOG file is available to list differences since last version.

To generate it, install git-chglog.

To update it, execute the following command:

make changelog

License

This software is granted under EUPL license, version 1.2 only.

Contact

This project is available under genese project Github page.