Docker installation

Here are 2 tutorials to run Exakat on your code. You may install exakat with the projects folder, and centralize your audits in one place, or run exakat in-code, right from the source code. You may also run exakat with a bare-metal installation, or as a docker container.

  • Docker container

  • with projects folder

  • within the code

All four tutorials offer the same steps : + Project initialisation + Audit run + Reports access

Docker container, with projects folder

This tutorial runs exakat audits, when source code are organized in the projects folder. Any folder will do, since exakat is now hosted in the docker image.

Initialization

Go to the directory that contains the ‘projects’ folder.

Init the project with the following command :

docker run -it --rm -v /Users/famille/Desktop/analyzeG3/projects:/usr/src/exakat/projects exakat/exakat:latest exakat init -p sculpin -R https://github.com/sculpin/sculpin -git

This will create a ‘projects/sculpin’ folder, with various documents and folder. The most important folder being ‘code’, where the code of the project is fetched, an cached. See _Commands for more details about the init command.

Execution

After creating the project, an audit may be run from the same directory:

docker run -it --rm -v /Users/famille/Desktop/analyzeG3/projects:/usr/src/exakat/projects exakat/exakat:dev exakat project -p sculpin

This command runs the whole cycle : code loading, code audits and report building.

Once it is finished, the report is available in the projects/sculpin/report/ folder. Open projects/sculpin/report/index.htmll with a browser.

More reports

When running exakat with the projects folder, reports may be configured before the run of the audit, in the config.ini file, or in command line, or extracted after the run.

After a first audit, use the report command. Here is an example with the Uml report.

docker run -it --rm -v /Users/famille/Desktop/analyzeG3/projects:/usr/src/exakat/projects exakat/exakat:dev exakat report -p sculpin -format Uml

Reports may only be build if the analysis they depend on, were already processed.

In command line, use the -format option, multiple times if necessary.

docker run -it --rm -v /Users/famille/Desktop/analyzeG3/projects:/usr/src/exakat/projects exakat/exakat:dev exakat project -p sculpin -format Uml

In config.ini, edit the projects/sculpin/report/config.ini file, and add the following lines :

project_reports[] = 'Uml';
project_reports[] = 'Plantuml';
project_reports[] = 'Ambassador';

Then, run the audit as explained in the previous section.

The full list of available reports are in the _Reports section.

New run

After adding some modifications to the code and committing them, you need to update the code before running it again : otherwise, it will run on the previous version of the code.

docker run -it --rm -v /Users/famille/Desktop/analyzeG3/projects:/usr/src/exakat/projects exakat/exakat:dev exakat update -p sculpin
docker run -it --rm -v /Users/famille/Desktop/analyzeG3/projects:/usr/src/exakat/projects exakat/exakat:dev exakat project -p sculpin

Docker container, within the code folder

This tutorial runs exakat audits from the source code repository, with a docker container.

Installation

Refer to the _Installation section to install Exakat on docker.

Initialization

Go to the directory that contains the source code.

Create a configuration file called .exakat.yml, with the following content :

project: "name"

This is the minimum configuration for that file. You may read more about _Configuration in the dedicated section.

Execution

After creating the configuration file, an audit may be run from the same directory:

docker run -it --rm -v $(`pwd`):/src exakat/exakat:latest exakat project

This command runs the whole cycle : code loading, code audits and report building. It works without initial configuration.

Once it is finished, the report is displayed on the standard output (aka, the screen).

More reports

When running exakat inside code, reports must be configured before the run of the audit : they will be build immediately.

Edit the .exakat.yml file, and add the following lines :

project: "name"
project_reports:
  - Uml
  - Plantuml
  - Ambassador

Then, run the audit as explained in the previous section.

This configuration produces 3 reports : “Ambassador”, which is the default report, “Uml”, available in the ‘uml.dot’ file, and “Plantuml”, that may be opened with plantuml.

The full list of available reports are in the _Reports section.

New run

After adding some modifications to the code, run again exakat with the same command than the first time. Since the audit is run within the code source, no explicit update operation is needed.

Check the .exakat.yml file before running the audit, to check if all the reports you want are configured.

docker run -it --rm -w /src -v $(pwd):/src --entrypoint "/usr/src/exakat/exakat.phar" exakat/exakat:latest project