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.