Chapter 1. Meeting the Requirements

This page lists the software required to install and use DOC, first for development activities, then for deployment.

1. Using an Operating System

The operating system must support a version of the Docker Engine compatible with DOC. For more details, refer to Section Using Docker. This includes:

  • Windows Pro 10 or above,

  • Linux 64-bit, and

  • macOS 10.15 (Catalina) or above. Supported until 15.x (Sequoia), except for 14.4 with Apple Silicon (14.4.1 should be used instead).

2. Using a Terminal

The tools required or provided by DOC make use of Unix shell scripts. As a consequence, you need to use a terminal.

If you are developing on Windows, you need a Unix shell emulator, such as:

  • Windows Subsystem for Linux (WSL 2)

  • Git Bash (which comes with the Git installation on Windows)

  • Cygwin

All shell commands described in the present documentation should be run in the Unix shell emulator. They will not behave appropriately if you are using Windows PowerShell.

In addition, you may find it useful to install a tool that will give you access to multiple terminals from one window, such as the ConEmu terminal (see https://conemu.github.io/).

3. Using Programming Languages

Programming languages requirements for DOC are as follows:

  • Java Development Kit (JDK) 17

  • Node.js 20.17.0 (its patches are also supported)

  • Python 3.12.0 (its patches are also supported)

    [Note]

    Note that for Python development on Windows, Microsoft Visual C++ Build Tools 14 or above is also required.

3.1. Using Java

You will need to install a Java Development Kit for Java 17. To this end, you can go to the website of one of the providers of JDKs, such as https://www.adoptium.net/, and proceed with the installation.

You can check your installation with the following command.

$ javac --version
javac 17[.0.0 or above]

If the above command does not yield the aforementioned version, this is probably because you have several JDKs installed on your machine. There are several solutions to tell your system which JDK to use, often dependent on your operating system. An OS-independent solution is SDKMAN (see https://sdkman.io).

3.2. Using Python

If you want to develop in Python, typically to implement a Python worker, you will need to install a recent version of Python. For more details, refer to Chapter Meeting the Requirements.

You can download and install Python from www.python.org.

You can then check your installation with the following command.

[Note]

Note that, on some installations, the executable is called python3.

$ python --version
Python 3.12.0

In addition, some Python dependencies on Windows require the installation of Microsoft Visual C++ Build Tools. To do so:

  • Download and install the Visual Studio Installer

  • Run the installer to install Visual Build Tools with the Desktop Development with the C++ component enabled (from the " Workloads" tab).

4. Using Docker

Memory requirements: To run a complete application with Docker images, you should consider dedicating at least 6 GB of memory to the Docker environment. As a consequence, it is recommended to have a laptop with at least 16 GB of RAM.

Docker Desktop licensing: Using Docker on a development machine that runs Windows or macOS typically requires to use the Docker Desktop tool. Since February 1, 2022, large companies are required to pay a subscription to use Docker Desktop as described in the Docker blog and FAQ.

DOC requires Docker Engine 20.10.15 or above with the embedded compose extension.

[Note]

Note that,on macOS, both the Intel (amd64) and the Apple Silicon (arm64-v8) architectures are supported.

Docker technology is used to package and run the various microservices of your application. DOC also provides a few components as Docker images.

You will need to install a recent version of Docker to develop with DOC. The typical way to install Docker for development is to download and install the Docker Desktop tool from https://docs.docker.com/get-docker/.

You can then check your Docker installation with the following commands (you may need to use sudo on Linux).

$ docker version
Docker version 20.10.15 [or above]

If you are developing on Linux, you may find it useful to add yourself to the docker Unix group.

To properly run a full application within Docker, you must ensure that at least 6 GB of RAM is allocated to Docker. This is done using the Docker Desktop application.

Figure 1.1. Configuring Docker Desktop Memory
Configuring Docker Desktop Memory

On Windows, you must also ensure that your drive is accessible to Docker.

Figure 1.2. Configuring Docker Desktop Access to the Drive
Configuring Docker Desktop Access to the Drive

Also on Windows, if you have trouble sharing the C drive with Docker containers, you might want to look at the following solution: www.mattwoodward.com/2019/05/09/docker-on-windows-10-sharing-a-drive-when-logging-in-with-a-microsoft-account/.

5. Using a Deployment Environment

For deployment to production, DOC is compatible with Kubernetes 1.28 up to 1.30. Later versions have not been tested. For more details, refer to https://kubernetes.io.

For deployment for development testing purposes, DOC is also compatible with Docker on the configurations that are supported for development. For more details, refer to Section Using Docker.

6. Using a Browser

The applications generated using DOC include a web frontend service. When building this service, tests are run using the Karma test runner, which requires the presence of a Google Chrome browser on the machine.

You can download and install it from www.google.com/chrome/.

To access the frontend of applications created with DOC, users also need a web browser. The supported browsers are the two latest desktop versions of:

  • Google Chrome,

  • Mozilla Firefox,

  • Microsoft Edge Chromium.

7. Using an Integrated Development Environment

DOC does not include an Integrated Development Environment but such a tool is a must have for development activities. Typical options include JetBrains IntelliJ IDEA (the Community Edition is available for free) and Microsoft Visual Studio Code (free).

The project you can generate as described in Chapter Generating the Application Structure, will be fully configured to compile with Gradle. It can be run either from the command line using, for example, gradlew bootRun or through Docker. This section explains how you can work on this project using an Integrated Development Environment, such as JetBrains IntelliJ IDEA.

[Note]

Note that DOC code uses the Spring boot library, so we recommend using IntelliJ Ultimate edition that provides enhanced support for it.

To start working on your project under IntelliJ, simply open it. IntelliJ will then detect the presence of Gradle build scripts and will import the information they contain to create the project structure in terms of IntelliJ modules, dependencies, external libraries, etc.

There are several ways to open a project in IntelliJ. When you launch IntelliJ for the first time, you are presented with a splash dialog with several options: choose Open.... Then, if you already have a project open in IntelliJ, select the File > Open... menu entry. In all cases, choose the root directory of your project in the file chooser that appears.

In addition to the Java processing capabilities of IntelliJ, you can easily configure it to develop and debug Python code as follows:

Procedure 1.1. To configure IntelliJ for Python

Information regarding other products than DOC is subject to change without notice.

  1. Install the JetBrain Python plugin for IntelliJ.

    If you have not yet initialized the Python virtual environment, open a terminal and run ./gradlew pythonInitVirtualenv. Remember to do it every time you update Python dependencies.

  2. If you have not yet initialized the Python virtual environment, open a terminal and run ./gradlew pythonInitVirtualenv. Remember to do it if you update Python dependencies. For more details, refer to Section Using Gradle Configuration Files.

  3. From the IntelliJ menu, click on File > Project Structure. A pop-up window opens.

  4. In Section SDKs, add the value virtualenv generated by Gradle as follows:

    1. Click on the button +.

    2. Select Existing environment and provide the Interpreter from one of the following directories:

      • <project-root>/.gradle/python/virtualenv/bin/python on Linux.

      • <project-root>\.gradle\python\virtualenv\Scripts\python.exe on Windows.

      Select Existing environment and provide the Interpreter from directory .gradle/python/virtualenv/bin/python located at the root of the project.

      Figure 1.3. Selecting the Python Environment in IntelliJ
      Selecting the Python Environment in IntelliJ

  5. In the section Modules, import the Python modules for the project as follows:

    1. Click on the button +.

    2. Select the following files:

      • gene-model/gene-model-dom-python/python/python.gene-model-dom-python.iml

      • processing/python-engine/python/python.python-engine.iml

      • workers/python-engine-worker/worker-shell/python.worker-shell-python.iml

      Figure 1.4. Adding the Project Python Modules to IntelliJ
      Adding the Project Python Modules to IntelliJ

You can now develop with IntelliJ, run tests with debug, navigate through the code, etc.

You can also use IntelliJ to debug your running Python worker by adding breakpoints.

Procedure 1.2. To Add Debug Breakpoints into Python Workers using IntelliJ

Information regarding other products than DOC is subject to change without notice.

  1. From the IntelliJ tab left tool bar, click on Services. The tab opens.

  2. In the Tab toolbar, click on the menu item + Add Service > Run Configuration Type > Gradle. The configuration is updated.

  3. In the Tab toolbar, click on the menu item + Add Service > Run Configuration Type > Python Debug Server. The configuration is updated.

  4. Start the Python Engine Worker run configuration in debug mode through IntelliJ. For more details, refer to the Official IntelliJ documentation.

  5. Start the Python Debug Server run configuration.

  6. Then, you can add breakpoints into your Python code. For more details, refer to the Official Python documentation.