TUI 6M Environment

This package provides a reference environment for 6M components. When you are writing a 6M component, you can use this tool to emulate the build and runtime environments of 6M.

This tool supports mono- or multi-repository 6M components. You can install it standalone or as a dev dependency of your 6M repository.

Prequisites

You will need a recent version of NodeJS (>= 10.12) and Docker (>=18.02) installed on your development machine. So if necessary, please install or update NodeJS and Docker first.

Installation

As a dependency of a 6M component

Usually, you will install this package as a part of your 6M component (in case you have separate repositories for frontend and middlelayer: the frontend part).

npm install --save-dev @tuicom/6m-env

Standalone

For a standalone installation, clone the repository and install the dependencies:

git clone https://github.com/tuicom/6m-env
cd 6m-env
npm install

Usage

Setup

The setup is necessary if any of the following is true:

• You are running this tool in standalone mode.
• Your 6M component is setup in a multi-repo layout (i.e. frontend and middlelayer in separate repos).
• Your middlelayer needs runtime configuration, e.g. custom environment variables.

If nothing of the above applies, proceed to the Build section.

Environment variables

You can control the behaviour of these tools through a set of environment variables. The following variables are available:

|name|explaination|default| |----|---|---| |frontend_repo|the local path (absolute or relative) to the frontend repository|$work_dir (see below)| |middlelayer_repo|the local path (absolute or relative) to the middlelayer repository|$work_dir (see below)| |middlelayer_args|runtime arguments for the middlelayer (passed to docker run)|(empty)| |work_dir|working directory|the directory where the command is executed, i.e. $(pwd)| |content_dir|directory where generated files, such as build artifacts are put|$work_dir/.6m-env| |config_file|file from which environment variables are loaded (see below)|$work_dir/6m-env.conf|

Config file

Environment variables can also be put into a config file. The default file location is $work_dir/6m-env.conf, but you can overwrite it with the config_file environment variable.

For example, create a file named 6m-env.conf in the repository’s root with the following content:

# the local path (absolute or relative) to the frontend repository
frontend_repo=../my-frontend/

# the local path (absolute or relative) to the middlelayer repository
middlelayer_repo=../my-middlelayer/

# runtime arguments for the middlelayer (passed to `docker run`)
middlelayer_args=

Build

Run the following to build your component:

bin/build.sh # when installed standalone
npx 6m-build # when installed as a dependency

If you need to pass any of the environment variables, prepend them to the command invocation, for example:

middlelayer_repo="../my-middlelayer" npx 6m-build

This command will build the frontend assets and the middlelayer image. The assets will be stored in $assets_dir (see above). The middlelayer will be stored in your local Docker registry.

Validate generated assets

To validate the 6m.json file and the generated assets, you can use the following command:

bin/validate.js /path/to/6m.json # when installed standalone
npx 6m-validate /path/to/6m.json # when installed as a dependency

The command expects the location of the 6m.json file as argument. It will first validate the contents of the 6m.json file against a JSON schema, then check the files referenced therein.

Run

To run the project, execute:

bin/run.sh # when installed standalone
npx 6m-run # when installed as a dependency

Environment variables can be passed here, too. See the examples above to learn how this works.

The 6m-run script will put the assets into an Nginx container and start another container from the middlelayer image. If everything went right, the 6m-run tool will give you a demo page where you can see your component in action.

If it helps, you can modify the files in $content_dir – the files in the assets directory as well as the demo.html file and start 6m-run again. When re-running the script, it will re-create the frontend container with the new assets and start it up. If you made modifications inside the $content_dir, don’t forget to port them into your source code if neccessary, otherwise they will be lost after the next 6m-build. Note that middlelayer modifications always require you to execute 6m-build in order to be applied.