Installation

Installation requirements

The first step is to check the supported Server versions and installation requirements.

Installing the python agent module

There are two different installation methods. The first one is manual, for DevOps that prefer manual (but more error-prone) control. The second one uses a wizard-style script that can be optionally guided by a configuration file to configure everything.

Wheel package + manual configuration

This method implies installing the .whl using pip and then configuring it manually according to the steps described in the following sections.

Retrieve and copy the core binary

Run the script fetch-portable-core.

./build-tools/fetch-portable-core

This will download the appropriate core for the architecture (java, linux, linux-static, macos or windows) and install it under the directory hdiv_agent/bin/(architecture)/hdiv-ee-portable-core (suffixed with .exe when the architecture is windows).

Edit the env.properties config file

Copy the env.properties.template that can be found in hdiv_agent/settings under the Python package installation directory to the desired destination directory (if in doubt, run python -c 'import hdiv_agent; print(hdiv_agent.__file__)'). Rename it to env.properties and edit these options:

• hdiv.config.dir: Config directory for the binary core. Must be a directory writable by the user running the Python web application.
• hdiv.mandatory.app.name: Name of the web app. Can be any string.
• hdiv.mandatory.app.version: Version of the web app.
• python.core.[platform].bin: Path to the core binary matching the one you installed on the previous step. You only need to update the option matching the used platform.

Install the license.hdiv file

Copy or move the license.hdiv file that you should already have (it is not included in the installation package) to the directory you set up in the previous step as hdiv.config.dir and ensure it is readable by the app system user.

Install the agent hook

Find the WSGI module used to start your app (this will usually be called wsgi.py or <something>.wsgi) and add these lines above any other imports:

import hdiv_agent
hdiv_agent.start()

For Django's runserver command to also run with the agent, the same must be done in Django's manage.py file.

Generate the pre-imports module (optional)

This step is optional, but recommended.

In order to move some import-time runtime cost to the startup of the application, you need to create pre-importable module and call it from the wsgi file above. To do this, change to the root directory of your project and run:

python -m hdiv_agent.scripts.preimporter_generator -r . -o preimport.py

This will generate the preimport.py file that you now need to import from the wsgi module:

import hdiv_agent
import preimport  # change the location or move the file as needed
hdiv_agent.start()

In case you want the pre-importer not to include a specific module or modules, you can include them with the --blacklist option as a comma-separated list.

Restart

Restart your web server and, if needed, your Python runtime like uWSGI, gunicorn or others, and the agent should start working. Note that on the first request after each restart the core will be executed and initialized so that request could be a fraction of a second slower than others.

Wheel package + guided configuration

This method starting point is also installing the .whl package but after that is done the script hdiv_python_agent_configure can be run, which will start the guided installation process. The first time it is run, the script will install a file .hdiv_python_installer.ini in your $HOME directory. This file optionally can be edited to manually set some or all of the required paths or even create a totally unattended installation.