2 Configuration & Installation

2.1 Configuration (optional)

The PKM server has a configuration file, named pkm_config.json.

The PKM server comes with a default configuration file available on the pkm-api gitlab repository.

The default configuration file, whose content is outlined below, is good for most people:

{
  "debug": false,
  "db_host": "pkm-api_mongodb_1:27017",
  "pkm_db": "pkm",
  "session_timeout": "1 d",
  "secret_file": "secret",
  "git_root_directory": "git-root",
  "git_max_parallel_read_files": 1,
  "git_max_parallel_write_files": 1,
  "git_remote_timeout": "10 m",
  "server_request_body_limit": "256MB",
  "project": {…},
  "schemas": {…},
  "types": {…},
  "file_types": […]
}

The JSON schema of the configuration file is available on the pkm-api gitlab repository.

2.2 Easy installation (no build required)

A program that provides a command line interface and a control center for managing the services (download, install, update, start …) of DECODER EU Project Tool-chain, as a local instance without remote access, is available at https://gitlab.ow2.org/decoder/docker-deployment. This program is based on docker and docker-compose.

To run the program, do the following at the command prompt:

$ ./app/bin/decoder-eu

On the first use, you should install then start the toolchain, see Figure 1 below, which shows the control center user’s interface:

Figure 1: DECODER EU Project Tool-chain control center

As soon as the graphical user interface has started in your default web browser, you can log in using the preconfigured administrator account whose login is “admin” and the password is “admin”, see Figure 2 below:

Figure 2: Login screen

Minimum Hardware Requirements

Dependencies

Command line interface

Usage: decoder-eu [<options>] [<commands>]

Options:
    --version
        Outputs version information and exit

    --help
        Display this help and exit

    --user-pref-dir <directory>
        Set the directory where the user's preferences are located (default: ~/.config/decoder-eu)

    --user-data-dir <directory>
        Set the directory where the user's data are located (default: ~/.local/share/decoder-eu)

Commands:
    start
        Starts the DECODER EU Project Tool-chain services then opens the GUI in your default browser

    gui
        Opens the GUI in your default browser

    stop
        Stops the DECODER EU Project Tool-chain services'

    status
        Shows the status of the DECODER EU Project Tool-chain services

    shell
        Starts a shell with a preset environment

    reset
        Resets all data (but preserve your saved preferences) (default: in ~/.local/share/decoder-eu)

    select-tools
        Select the tools considered for start, install and update commands

    configure
        Edit configuration file (default: in ~/.config/decoder-eu/config)

    delete-prefs
        Delete your saved preferences (default: in ~/.config/decoder-eu)

    install
        Downloads, install, and preconfigure DECODER EU Project Tool-chain ready to use

    update
        Update DECODER EU Project Tool-chain (without altering your saved preferences)

    uninstall
        Uninstall DECODER EU Project Tool-chain (but preserve your saved preferences)

2.3 Minimal Docker installation

The installation procedure in this section applies only to PKM and some parsers for which pkm-api gitlab repository hosts the source code. This installation procedure is not for all the docker images of the DECODER EU Project Tool-chain. For a complete installation, refer to Section 2.2.

The built and installed services are the following:

This minimal set of services handles the PKM (document management and querying) and parsing C, C++, .docx, and executable binary files.

2.3.1 Setting up administrators’ credentials (optional)

MongoDB and PKM require an initialization. When PKM and MongoDB services start for the first time, the initialization starts automatically. Once initialized, the MongoDB and PKM services gracefully ignore later attempts to initialize. The stock MongoDB database is virgin with security disabled, so the initialization of the MongoDB service consists in creating an administrator (a “superuser”) in database admin (admin@admin), who can create users and roles in any MongoDB database, then enabling MongoDB security. The initialization of the PKM service consists in creating the PKM management database (where all the PKM users live and where the list of PKM projects is) and then an initial PKM administrator. That PKM administrator can later create other users and even other PKM administrators in the PKM management database. The PKM initialization runs on behalf of the MongoDB “superuser”.

The credentials used during initialization are in mongodb/credentials.json:

{
  "superuser": "admin",
  "superuser_auth_db": "admin",
  "superuser_password": "admin",
  "pkm_admin": "admin",
  "pkm_admin_password": "admin"
}

The default credentials are:

File pkm_config.json defines the authentication database for the PKM administrator, i.e. the PKM management database, see property pkm_db (default: pkm).

Later after the initialization, MongoDB shell allows changing the MongoDB superuser credentials while the PKM application programming interfaces (or MongoDB shell) allows changing the PKM administrator credentials.

2.3.2 Building the docker images

Do the following to build the PKM and some of the parsers docker images:

$ docker-compose build

2.3.4 Starting the docker services

Do the following to start the PKM some of the parsers docker services:

$ docker-compose up