Adding Built-in workflows to the BlueCat Gateway Container - Platform - BlueCat Gateway - 24.1

Gateway Administration Guide

Product name
BlueCat Gateway

Before deploying workflows to your Production Gateway container, we recommend that you first build your image in a Test environment that contains custom workflow/application data, permissions, configurations, and customizations. Setting up this kind of "black box" container provides consistent deployments and improved resiliency and redundancy. It helps workflow developers write custom workflows, reduce the number of manual changes, better deploy their work to production, and maintain container resiliency.

To add built-in workflows to a container, you must copy the workflows and the associated files to the /builtin folder via the copy command in Dockerfile.

Starting in BlueCat Gateway v20.12.1, Gateway transitions from providing /portal/builtin as a location for workflow developers to include workflows inside the image to providing /builtin as a location for including a full workspace inside the container. The Built-in workspace is not intended to be mounted, rather, it is a location to use when a new image is created based on a Gateway image. It is a recommended location for the workflow developers to add their content.

  • Built-in workflows cannot be deleted, exported, or imported.

  • The Built-in workspace supports the following:

    • Group Settings

    • IdP SSL certificate

    • Resources

    • TSIG key

Follow the steps below to add a sample workflow to the BlueCat Gateway container:

  1. Create a local directory for the files that you want to include in /builtin inside the container.

  2. For each workflow you want to add, create a subfolder within this folder. For example, to add a workflow for adding an alias record under a folder named "Alias Record", you could create an add_alias_record folder as follows:


    The structure of the builtin/ workspace should match the custom workspace /bluecat_gateway. For example:

    • /builtin/workflows

    • /builtin/

    • /builtin/permissions.json

    • /builtin/customizations/.mailsecret

    When adding an SSO configuration to /builtin, you must add both the settings.json and advanced_settings.json files.

  3. Add all desired workflows to the subfolders. Write the following script in a Dockerfile:

    USER root
    # you can add any other 3rd party libraries here e.g
    # RUN pip3 install openpyxl==3.0.5
    COPY ./workflows/ /builtin/workflows/
    COPY ./ /builtin/
    COPY ./permissions.json /builtin/
    # Ensure the content is available if the container is run with a custom User ID.
    RUN \
        chgrp -R 0 /builtin                                                     && \
        chmod -R g=u /builtin
    USER flask
    Note: This file must be named Dockerfile. For more information on Dockerfiles, refer to the official Docker documentation (
    Note: All folders and files added to the /builtin or /bluecat_portal folders should have rwx permissions.
    Attention: If you add the configuration and permissions files to both the /builtin and the bluecat_portal folders, the settings in the bluecat_portal folder are used.
  4. Navigate to the directory that you created in step 1 and run the following docker build command to create an image using the Dockerfile:

    docker build . -t <custom_project:some_version>

    An image called custom_project:some version is created.

  5. Instantiate the container by running the docker run command using custom_project:some version

    docker run -d \
    -p 80:8000 \
    -p 443:44300 \
    -v <path_to_mapped_data_directory>:/bluecat_gateway/ \
    -v <path_to_mapped_log_directory>:/logs/ \
    -e BAM_IP=<your bam ip or url> \
    -e BAM_API_VERSION=<BAM API Client version, either 1 or 2> \
    --name bluecat_gateway custom_project:some_version
  6. Log in to BlueCat Gateway.

  7. (Optional) If you don't have built-in configurations and permissions, assign permissions to user groups for each workflow. After you do so, workflows to which users have access are listed in the left navigation bar.