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. |

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) |