Skip to main content

Installation

Q247 can connect to the version control system in two ways: from Q247's secure cloud infrastructure (Cloud Plugin) or through a plugin installed locally, in the Client's infrastructure (Private Plugin). Functionally both modes work the same; they differ only in where the scanning process physically runs.

Deployments are managed in Configuration, in the Plugins section. Each deployment has its own mode marker on the list, Cloud or On-Premise, and its own list of Connectors.

Plugins section with the list of deployments and their connectors

Cloud Plugin​

This is the default mode. It requires no configuration in the Q247 UI, nor any involvement from the Client's DevOps team, apart from one thing: opening network access from the Cloud Plugin to the Client's SCM system. Cloud Plugin is available to every client and enabled by default.

At the Client's request, an additional layer of security can be added between the Cloud Plugin infrastructure and the Client's infrastructure, for example a dedicated VPN channel. Full security details are described in Enterprise Plugin Security.

Connection requirements for Cloud Plugin​

Network routing has to be opened between the Q247 cloud plugin's outbound address and the REST API endpoint of the Client's SCM system. The current address is provided by the Q247 deployment team.

Private Plugin​

The Client creates its own deployment in the panel, downloads the configuration file and the plugin file for it, and runs the process in its own infrastructure.

1. Creating a deployment​

In Configuration, in the Plugins section, the Add Plugin button opens a form with a single field.

Add plugin form with a name field

FieldWhat to enterExample
Namea unique deployment name, to recognize it on the listWarsaw Plugin

Once confirmed, the deployment appears on the list, marked as On-Premise, with an empty connector list.

2. Downloading the files​

Two files are needed, and they are downloaded from two different places:

  • Config, a button next to the specific deployment on the list. Downloads the configuration file generated for that deployment. The button appears next to On-Premise deployments.
  • Plugin File, a button in the header of the Plugins section. Downloads the latest version of the plugin itself. It appears once the organization has at least one On-Premise deployment.
Order of downloading the files

The configuration file is generated for a specific deployment, so create the deployment first, and only then download the files. Before adding the first On-Premise plugin, neither of these two buttons is on the screen.

Both files (config.cfg and q247-enterprise-plugin-linux-*) must land in the same directory on the target server.

3. Installation and startup​

Starting the plugin:

nohup ./q247-enterprise-plugin-linux-vx.x.x --q247-ep-plugin-prod > q247-plugin.log 2>&1 &

Replace x.x.x with the version number of the plugin file you downloaded (Enterprise Plugin), as it appears in the file name.

Checking whether the process is actually running:

# ps -efww | grep -i q247
q247 1372705 1 5 Apr17 ? 15:59:29 ./q247-enterprise-plugin-linux-vx.x.x --q247-ep-plugin-prod

While running, the plugin uses these files and directories:

  • q247-plugin.log: plugin logs.
  • q247-working: working directory, where the plugin temporarily stores data fetched from Git repositories.
  • plugin.data, plugin.data-shm, plugin.data-wal: the plugin's local data store files.

For a new installation, the configuration file downloaded from the panel can be used as it is. The panel generates it anew with every download, with default settings, so it does not carry over changes you made earlier in your own file. Besides the backend address and the deployment credentials, the file contains the default listening ports and the list of plugin modules, including the Jira and Confluence integration modules and the CICD module (CICD entry in the configuration file).

Preparing the Client's environment​

Beyond simply starting the process, the following requirements must be prepared in the Client's infrastructure.

Network access​

The plugin connects outbound: to the version control system, to the Jira, Confluence and Azure DevOps Server instances, and to the Q247 backend. The Azure Boards and Azure Wiki integrations work by polling only, so they add no inbound traffic.

If the Jira or Confluence integrations run in the Data Center variant and ingest data through webhooks, inbound traffic from those instances to the plugin is added. The file downloaded from the panel sets port 443 for HTTPS and port 80 for HTTP by default. The plugin starts one listener: HTTPS if it can load the TLS certificate and private key, otherwise HTTP (TLS certificate for the webhook receiver). Allow traffic through the firewall only to the port on which the plugin is actually running and enter that port in the connector's Plugin server Port field. This is usually the HTTPS port. The traffic stays inside the Client's network.

In API polling mode, the plugin connects to Jira and Confluence outbound only, and the connector form does not show the plugin server fields then. → Ingestion method in Jira and in Confluence

The Client's infrastructure administrator sets non-default ports in plugins.http.port and plugins.https.port in config.cfg. The following fragment of the plugins section sets port 60080 for HTTP and 8443 for HTTPS:

{
"plugins": {
"http": {
"port": 60080
},
"https": {
"port": 8443
}
}
}

Change only these two values and keep the remaining settings from the configuration file downloaded from the Q247 panel unchanged.

TLS certificate for the webhook receiver​

The webhook receiver can work over HTTPS, which requires providing a certificate and private key for the address under which the plugin will be visible to Jira and Confluence.

A missing certificate does not stop the plugin

The plugin will then start with unencrypted listening and keep working, with no error visible in the Q247 panel. Webhook traffic stops being encrypted even though the configuration looks complete, which is why it is worth confirming the certificate at the start of the deployment, not after the fact.

Proxy and TLS inspection at the firewall​

If outbound traffic from the Client's network goes through an explicit proxy, its address and any authentication data need to be given to the deployment team. A transparent proxy requires nothing.

If the firewall terminates TLS connections and re-signs them with its own certificate, the plugin will not recognize the Q247 backend's certificate and the connection will fail. In that case the Client provides a PEM file with the corporate CA certificate. The same applies to a situation where the Jira, Confluence or Git server instance has a certificate from a private CA. → Root CA certificate in the configuration file

Root CA certificate in the configuration file​

If Jira Data Center, Confluence Data Center or GitLab use certificates issued by an in-house CA (for example generated with OpenSSL, step-ca or AD CS), the plugin must know the root CA certificate to verify those servers. The path to the PEM file with that certificate goes into an ssl section that the administrator adds directly to the main JSON object in config.cfg, next to the existing fields such as endpoint and apikey:

{
"ssl": {
"caFilePath": "/path/to/rootCA.pem",
"sslMode": "strict"
}
}

Below is an example config.cfg with the ssl section added right after the dryrun field.

Fragment of config.cfg with the ssl section in the main JSON object

FieldValue
caFilePathpath to the PEM file with the root CA certificate, stored on the server where the plugin runs
sslModestrict keeps full certificate verification enabled

A single file given in caFilePath applies to all of these servers, so if they use different CAs, put their certificates together in one PEM file. The plugin reads config.cfg at startup, so restart it after adding the section. If the certificate file cannot be loaded (wrong path or missing permissions), the plugin writes an error to its log and falls back to the default verification, and connections to servers with a private CA keep failing with a certificate error.

CICD entry in the configuration file​

Collecting the history of CI/CD deployments requires plugin version q247-enterprise-plugin-linux-v2.7.9 or later and the CICD module enabled in config.cfg. The plugin modules are listed in the items array in the plugins section, and the CICD module is enabled by the entry { "code": "CICD" } appended at the end of it, after a comma following the last existing element. The fragment below shows the plugins section with the entry added. The // comment stands in for omitted entries; the plugin allows such comments in config.cfg.

{
"plugins": {
"http": { "port": 80 },
"https": { "port": 443, "certsPath": "certs" },
"items": [
{ "code": "JIRA", "isUseJiraChangelog": true, "backfillMode": "apply" },
{ "code": "CONFLU", "backfillMode": "apply" },
// remaining existing entries unchanged
{ "code": "GIT_PR" },
{ "code": "CICD" }
]
}
}

The array works as a list of allowed modules: the plugin starts only the ones listed in it and adds no defaults. Replacing the whole array with the CICD entry alone would therefore disable the other modules, and pasting the full list from another file would overwrite their settings and could enable modules your installation has not used so far. Modules, including the Jira and Confluence integrations, work only thanks to entries in this array. A working integration therefore means the array is already in the file and you only need to append the CICD entry to it. In a file without a plugins.items array no module has worked so far, and adding it with the CICD entry alone enables only deployment collection.

After adding the entry, restart the plugin with the same command as for the installation. The module start is visible in the q247-plugin.log log after the line Started addon CI/CD Deployments.

A new file from the panel replaces your own settings

The config.cfg file downloaded from the panel already contains the CICD entry, but has default settings. Replacing your existing file with it removes the changes made there, including custom ports and the ssl section. Downloading a new file is suitable only for installations where the file has not been changed.

See also​