@imec-apt/duxis-cltools

duxis-cltools

Duxis project command line development tools.

See also:

• Changelog

Using the cltools in your Duxis Project

Add the duxis-cltools as a dependency in the package.json file in your Duxis project:

{
  "name": "my-duxis-project",
  "version": "0.1.0",
  "dx_version": "1.27.4",
  "dependencies": {
    "@imec-apt/duxis-cltools": "1.2.1"
  }
}

Cd in your Duxis project root and learn more about the dx commands with:

./dx help

Installing Auto-Completion

Auto-completion for the dx command is or can be installed on MacOS and Linux.

For MacOS, auto-completion support assumes that you installed bash auto-completion as instructed in this how-to article.

For Linux, move tmp_bash_completion.d/dx to /etc/bash_completion.d/dx:

sudo mv <path-to-package>/tmp_bash_completion.d/dx /etc/bash_completion.d/dx

e.g.:

sudo mv node_modules/@imec-apt/duxis-cltools/tmp_bash_completion.d/dx /etc/bash_completion.d/dx

Pull requests that add support for other platforms are more than welcome!

Test the cltools

Run the tests once:

npm test
yarn test

Or run the tests in watch-mode:

npm run test:watch
yarn test:watch

Local Development

To test your local version of cltools in a Duxis project, cd into the project's root directory and execute:

rm -f dx
ln -s <path-to-duxis-cltools>/dx.sh dx

To restore the project, execute:

rm -f dx
npm install
yarn install

Manual

The duxis-cltools provides the command line utility dx, which facilitates the development, testing and deployment of Duxis projects.

To develop, test or deploy a Duxis project, you first need to build the project with the dx build command. You can build in one of the four following modes. The DX_ENV columns shows the value for the DX_ENV environment variable in

Command	Mode	DX_ENV	NODE_ENV	Description
./dx build	Production	prod	production	The default mode for deployment.
./dx build --dev	Development	dev	development	The standard development mode.
./dx build --dxdev	Duxis-development	dxdev	development	To be used when co-developing Duxis Foundation. (1)
./dx build --test	Test	test (prod(2))	test	To be used for running the tests.
./dx build --dxtest	Test	test (dxdev(2))	test	To be used for running the tests when co-developing Duxis Foundation.

Note that to use the _dxdev_ or _dxtest_ modes, the `DXF_PATH` environment variable in your `.env` file should be properly configured. The build-time environment.

The following table shows the values for the NODE_ENV and DX_ENV environment variables for each of the standard Duxis project modes.

Mode	NODE_ENV	DX_ENV
production	production	prod
test/dxtest	test	test
development	development	dev
dxdev	development	dxdev

Once you've built in one of these modes, you can use the other commands, depending on the mode, as shown in the following table:

| Command | prod | de/dxdev | test/dxtest | Description | | ------- |:---:|:---:|:---:|:---:| ----------- | | ./dx up |X|X|| Start the services. | | ./dx test |||X| Run the tests. | | ./dx inspect |X|X|| Inspect a service. | | ./dx logs |X||| Print the logs. | | ./dx stop |X|X|| Stop the services. | | ./dx down |X|X|| Stops containers and removes containers, networks, volumes and images created when running ./dx up (or ./dx test). | | ./dx restart |X|X|| Stop and restart the services. | | ./dx clean |X|X|X| Remove all images, containers, etc. | | ./dx clean --test |||X| Remove only test images, test containers, test volumes, etc. |

You can also use certain commands on one (or several) services, as shown in the following examples:

Command	Description
./dx build foo	Build the service foo in prodution mode. (1)
./dx build foo bar	Build the services foo and bar in prodution mode. (1)
./dx build --dev foo	Build the service foo in development mode. (1)
./dx up foo bar	Start the services foo and bar.
./dx restart foo bar	Start the services foo and bar.
./dx logs foo	Print the logs for the service foo.
./dx stop foo bar	Stop the services foo and bar.

1. Individual services should be built in the same mode as the last project build.

Some commands can only be used on a single service:

Command	Description
./dx inspect foo	Inspect the service foo (after it has been started).
./dx watch foo	Start the service foo in watch-mode.
./dx test --watch foo	Test the foo service in watch-mode.

Duxis Project Requirements

This section is under construction...

The following files and directories are required (or optional) in a Duxis project.

Path	Purpose
.env	Provides default values for (most of) the environment variables. Some additional variables are set by the dx cli.
dc.base.yml	Optional Docker Compose file that typically provides the common configuration, and is extended in the environment-specific compose files.
dc.dev.yml	The Docker Compose file that provides the development-specific configuration.
dc.dxdev.yml	Optional Docker Compose file that provides the extended Duxis-development configation.
dc.prod.yml	The Docker Compose file that provides the production-specific configuration.
dc.test.yml	The Docker Compose file that provides the test configuration.
...	(TODO)