@imec-apt/duxis-cltools NPM

duxis-cltools

Duxis project command line development tools.

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.

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.

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)