Black Duck Alert Quickstart (Docker Swarm - External Database)

• The Alert deployment files

• An existing Black Duck SCA server with enough free resources to start the containers (If your Black Duck SCA server is already running, stop it before attempting to deploy Alert).

• An external database which meets the specified requirements

• If the cluster is a multi-node swarm deployment, the containers need to be node locked, or backed by persistent storage.

See Installation Requirements for more information.

Unzip the blackduck-alert-<RELEASE>-deployment.zip archive downloaded from the link above into a location on your Black Duck SCA server.

• ALERT_ENCRYPTION_PASSWORD

• ALERT_DB_PASSWORD

• ALERT_DB_ADMIN_USERNAME

• ALERT_DB_ADMIN_PASSWORD

• ALERT_DB_SSL_CERT_PATH

• ALERT_DB_SSL_KEY_PATH

• ALERT_DB_SSL_ROOT_CERT_PATH

To create secrets, follow the normal docker commands - We recommend storing the values in a file which can be kept safe

docker secret create <STACK_NAME>_<SECRET_NAME> <FILE_CONTAINING_VALUE>

Example:

docker secret create hub_ALERT_ENCRYPTION_PASSWORD ALERT_ENCRYPTION_PASSWORD

For the purposes of this quickstart, we will use the following values:

Once the secrets are created, check that all nine exist by running docker secret ls

CREATE ROLE alertadmin LOGIN PASSWORD 'Blackduck1!';
CREATE ROLE alertuser LOGIN PASSWORD 'Blackduck1!';
GRANT alertuser TO alertadmin;
CREATE DATABASE alertdb WITH OWNER alertuser;

\c alertdb
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE SCHEMA IF NOT EXISTS alert AUTHORIZATION alertuser;

GRANT USAGE on SCHEMA alert to alertadmin;
GRANT CONNECT ON DATABASE alertdb TO alertadmin;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN schema alert to alertadmin;
GRANT EXECUTE ON ALL FUNCTIONS IN schema alert to alertadmin;

For the purposes of this quickstart guide, create a new file called docker-compose.local-overrides.alert.yaml inside your Black Duck SCA install directory.

---
version: "3.6"
services:
  alert:
    environment:
      - PUBLIC_ALERT_WEBSERVER_PORT=443
      - ALERT_DB_HOST=<POSTGRES_SERVER>
      - ALERT_DB_PORT=<POSTGRES_PORT>
      - ALERT_DB_SSL_MODE=allow
    secrets:
      - ALERT_ENCRYPTION_PASSWORD
      - ALERT_ENCRYPTION_GLOBAL_SALT
      - ALERT_DB_USERNAME
      - ALERT_DB_PASSWORD
      - ALERT_DB_ADMIN_USERNAME
      - ALERT_DB_ADMIN_PASSWORD
      - ALERT_DB_SSL_CERT_PATH
      - ALERT_DB_SSL_KEY_PATH
      - ALERT_DB_SSL_ROOT_CERT_PATH
secrets:
  ALERT_ENCRYPTION_PASSWORD:
    external: true
    name: hub_ALERT_ENCRYPTION_PASSWORD
  ALERT_ENCRYPTION_GLOBAL_SALT:
    external: true
    name: hub_ALERT_ENCRYPTION_GLOBAL_SALT
  ALERT_DB_USERNAME:
    external: true
    name: hub_ALERT_DB_USERNAME
  ALERT_DB_PASSWORD:
    external: true
    name: hub_ALERT_DB_PASSWORD
  ALERT_DB_ADMIN_USERNAME:
    external: true
    name: hub_ALERT_DB_ADMIN_USERNAME
  ALERT_DB_ADMIN_PASSWORD:
    external: true
    name: hub_ALERT_DB_ADMIN_PASSWORD
  ALERT_DB_SSL_CERT_PATH:
    external: true
    name: hub_ALERT_DB_SSL_CERT_PATH
  ALERT_DB_SSL_KEY_PATH:
    external: true
    name: hub_ALERT_DB_SSL_KEY_PATH
  ALERT_DB_SSL_ROOT_CERT_PATH:
    external: true
    name: hub_ALERT_DB_SSL_ROOT_CERT_PATH

At this point, we now need to merge the docker-compose.yml file found under blackduck-alert-<VERSION>-deployment\docker-swarm\external-db\hub into your Black Duck SCA instance. This, again, can be done in one of two ways:

• Merging the files together in your Black Duck SCA install directory

• Copying the file into your Black Duck SCA install directory with a name that distinguishes it (such as docker-compose.alert.yml)

For the purposes of this guide, we will create a new called docker-compose.alert.yml inside the main Black Duck SCA installation directory

version: '3.6'
services:
  alert:
    image: blackducksoftware/blackduck-alert:6.10.0
    ports: ['8443:8443']
    env_file: [blackduck-alert.env]
    healthcheck:
      test: [CMD, /usr/local/bin/docker-healthcheck.sh, 'https://localhost:8443/alert/api/about',
             /opt/blackduck/alert/security/root.crt, /opt/blackduck/alert/security/blackduck_system.crt,
             /opt/blackduck/alert/security/blackduck_system.key]
      interval: 30s
      timeout: 60s
      retries: 15
      start_period: 7200s
    volumes: ['alert-db-volume:/opt/blackduck/alert/alert-config/data']
    deploy:
    # Optional placement tag in the case of multi node swarm deployments.
    # The database must always persist on the same node
      #placement:
        #constraints:
        #- node.labels.type == db
      mode: replicated
      restart_policy: {condition: on-failure, delay: 15s, window: 60s}
      resources:
        limits: {memory: 2560M}
        reservations: {memory: 2560M}
volumes: {alert-db-volume: null}

Configuration of the Alert application such as authentication, database, providers, and channels can be performed using environment variables. Environment variable values are only used if there is no configuration data for the corresponding component already in the database. These will be read in at startup and configured by editing the docker-compose.local-overrides.yml file to include the environment variables you wish to set. The blackduck-alert.env file found under blackduck-alert-<VERSION>-deployment\docker-swarm\external-db\hub provides a look at the various parameters that can be set. See Environment Variables for more information. There are a number of different configuration options which can be statically set. For the purpose of this quick start guide, we will configure these within the UI.

At this point, we need to configure the Black Duck webserver to open up the routing for UI access. Run the following command within your main Black Duck installation directory:

sed -i "s/USE_ALERT=0/USE_ALERT=1/g" "hub-webserver.env"

This will expose Alert at https://<BLACK_DUCK_HOST_NAME>:8443/alert when the stack is deployed.

At this stage, we are ready to deploy. Run the following command within your terminal (bearing in mind any other configuration files required for BDBA, if in use):

docker stack deploy -c docker-compose.yaml -c docker-compose.alert.yaml -c sizesgen03\10sph.yaml -c docker-compose.local-overrides.yaml -c docker-compose.local-overrides.alert.yaml hub

Execute watch docker service ls within terminal to ensure that all services report a state of 1/1. Once everything is started, navigate to https://<BLACK_DUCK_HOST_NAME>:8443/alert

At this point, you will be presented with a login screen.

Figure 1. Alert login screen

After installation when Alert has been deployed and the login screen is available, the following action should be performed if the Alert database admin user does not have the role of superuser:

The Alert admin user declared by the ALERT_DB_ADMIN_USERNAME parameter requires a permissions update. These permissions are for the database admin to have select and update access to the databasechangeloglock table.

The following is an example of setting the required permissions:

GRANT SELECT, UPDATE ON public.databasechangeloglock TO alertadmin;