Create a GenoRing module

A GenoRing module template can be found in the GenoRing "modules/TEMPLATE" directory. A GenoRing module is a directory with the following structure:

• the directory name must only contain lowercase alpha-numeric characters and underscores and must start by a letter.
• README.md: a README file explaining the purpose of the module and how it works.
• TOLOCAL.md: a file explaining how to turn Docker service containers into "local" services handled either by the server hosting GenoRing or other available servers.

• env/: a directory containing environment files used by the module that will be use by GenoRing when the module will be enabled, to ask the admin to set the environment variable to configure the module and its services.
  Each environment file can hold multiple environment variables, one by line, following the format "VARIABLE_NAME=variable value" preceded by comments documenting the variable usage. Some @tags should also be present to explain how the variable is used:

  • SET: means it is recommended to customize the variable.
  • OPT: means the variable can be customize or left as is.
  • INS: means the variable is used at installation.
  • RUN: means the variable is used at runtime.

  Ex.:

  # - Drupal admin account name
  #   @tags: OPT INS
  DRUPAL_USER=genoring

  It is important do document variables with SET or OPT so they can be managed by GenoRing script at installation time. The first line of the comment block of a variable should contain the short variable description in one line. The next line should be an empty comment line or only contain dashes ('-'). The next comment lines should contain the complete description with explanations on how to fill the value. The comment block should then contain a "@default" annotation followed by a space and the default value (could be empty) and the "@tags" annotation stating the use of the variable.
  See "modules/genoring/env/genoring.env" for more examples.
  Note: enabled Docker Compose profiles can be provided to a container through an environment variable defined as "COMPOSE_PROFILES=${COMPOSE_PROFILES}". See "services" note for details on Docker Compose profiles.

• services/: a set of YAML files containing the Docker definition of each service provided by the module.
  See https://docs.docker.com/compose/compose-file/05-services/ for details.
  The definition should not include the "services:" element nor an element name for the service and should not include a "container_name" parameter as it will be automatically set by GenoRing using the YAML file name. The indentation must not include extra-spaces for readability as they will be automatically managed by the GenoRing script. To avoid conflicts between modules, service names should be prefixed by "genoring-" followed by their module name followed by a dash, unless a service could be shared amongst multiple modules.
  Note: 5 profiles are managed by GenoRing and can be used in the service definitions (ie. "profiles: [...]") to limit the use of a service to a given context:

  • "prod": set for production site.
  • "staging": set for staging site.
  • "dev": set for development site.
  • "backend": only enabled for back-end operations like module installation, update and uninstallation.
  • "offline": only enabled when the site is offline.

  Without specific profiles, the service is always loaded (if the module is enabled).
  Note: The "services" directory may contain a "alt" sub-directory with alternative services that can be used to replace the default ones. An "alt.yml" file contains alternative settings managed by GenoRing. Each alternative is defined by a (machine) name as YAML element key and contains a description string ("description" key), a list of substituted services (structured as current service name as key and new alternative service name as value under the "substitute" key), a list of new services to add ("add" key) and a list of services to remove ("remove" key).

• volumes/: a set of YAML files corresponding to named volumes shared across containers. These are not to be confused with volumes that can be defined in the services above. A module service can mount a shared volume in its "volumes" section but the point is that this shared volume can also be mounted by services in other modules for data sharing. See https://docs.docker.com/compose/compose-file/07-volumes/ for details.
  Since a same shared volume may be defined in multiple modules, the GenoRing script will ensure they use the same definition using the volume's version number provided as comment in the volume's YAML file header (ie. "# v1.0").
  The GenoRing script will only keep the latest sub-version definition (ie. if there is a 1.0 and a 1.1 definition, it will use the 1.1 definition) or the last definition met and will raise an error in case of different major versions and abort module activation (ie. 1.0 vs 2.0).
  Note: a 'genoring-' prefix is required to avoid collisions with other volumes managed by Docker.

• hooks/: a directory holding hook scripts. Hook scripts may be available or not for a given action and can be PERL scripts for local system actions or shell scripts (or others) that should be run in module containers. "local hooks" are usually called when all containers are down (except for the "state.pl" hook) while "container hooks" are launched on running containers when the system is fully loaded.
  Those scripts use special names to by triggered on specific events.

  • "backend_<service_name>.sh" will be triggered when GenoRing is started in "backend" mode.
  • "backup.pl" will be called on the local system when a backup is created to let the module manage its backup. The first argument provided is the backup machine name.
  • "backup_<service_name>.sh" will be called on the corresponding container when a backup is created to let the module manage/generate its backup. The first argument provided is the backup machine name.
  • "disable.pl" will be called on the local system when the module is disabled.
  • "disable_<service_name>.sh" will be called on the corresponding container to remove the modifications made by the "enable_<service_name>.sh" script.
  • "enable.pl" will be called on the local system when the module is installed or enabled.
  • "enable_<service_name>.sh" will be called on the corresponding container to alter other containers when needed (eg. adding menu items for the module features, pre-configuring Drupal modules, etc.).
  • "init.pl" will be called on the local system when the module is installed (and enabled).
  • "offline_<service_name>.sh" will be triggered when GenoRing is started in "offline" mode.
  • "online_<service_name>.sh" will be triggered when GenoRing is started normally (online mode).
  • "requirements.pl" will be called on the local system to check a module requirements when a module is installed. If the "requirements.pl" returns a non-zero exit code, it means some requirements are not met. Message output will be displayed to help the user know what is missing.
  • "restore.pl" will be called on the local system when a backup should be restored. The first argument provided is the backup machine name.
  • "restore_<service_name>.sh" will be called on the corresponding container when a backup should be restored to let the module manage/generate its backup restoration. The first argument provided is the backup machine name.
  • "start.pl" will be called on the local system when the GenoRing is started.
  • "state.pl" will be called on the local system when the status of the module is needed. When this script is not provided, the system will rely on Docker container state. However, in some cases like for the "genoring" service, the container might be running but may not be fully initialized. Therefore, such a script is needed to get the real container state. The script will just output a line with the container state. The ready state string to use is 'running'. See the corresponding template hook script for more details.
  • "stop.pl" will be called on the local system when the GenoRing is stopped.
  • "uninstall.pl" will be called on the local system when the module is disabled and uninstalled. The module will be disabled first and "disable.pl" will be called by the system before "uninstall.pl".
  • "update.pl" will be called on the local system when what is managed by the module (tools, data, etc.) needs to/should be updated.
  • "update_<service_name>.sh" will be called on the corresponding container to perform updates on things managed by the module (tools, data, etc.).
  • "upgrade.pl" will be called on the local system when the *GenoRing* module is updated to a newer version. The first parameter is the previous version of the module that needs to be upgraded using currently installed newer version.
  • "upgrade_<service_name>.sh" will be called on the corresponding container to perform upgrade of a GenoRing module. The first parameter is the previous version of the module that needs to be upgraded using currently installed newer version.

  Note: When running shell scripts inside containers, the GenoRing "modules" directory is copied in the container as "/genoring/modules" and allow access to module's files if needed (like the module "res" directory for instance).
  Note: Hook scripts may be called more than one time after a site installation. It is up to the script to not perform several time a same operation if it has already been done.

• src/: if the module uses custom containers, their sources will be provided there in sub-directories corresponding to service names (ie. YAML file names without the ".yml" extensions). Service names should always be prefixed with "genoring-" to avoid conflicts with other non-GenoRing Docker containers and must correspond to a module service name as defined in the module "services" directory.
  The "src/" directory must contain at least a "Dockerfile", a "Dockerfile.amd64" or a "Dockerfile.arm" file. "Dockerfile", if present, is used as default. A "Dockerfile.arm" may be provided but if not, it can be automatically generated by GenoRing at compilation time using the default version. Therefore, it is recommended to only provide a "Dockerfile" and only provide others for specific needs that can't be covered automatically.
• res/: if the module needs additional directory and files, that could be mounted in containers for instance, they should be put in this resources directory.
  Note: Any resource that could be edited by the administrator for customization should be copied in a sub-directory of the "./volumes/" directory at installation time.

When using other GenoRing services in a module, find the service server using "${COMPOSE_PROJECT_NAME}-SERVICE_NAME" where "SERVICE_NAME" is the name of the service. For instance, if you want to access JBrowse service, you would use "${COMPOSE_PROJECT_NAME}-jbrowse". This is necessary to support multiple GenoRing instances running on a same system.