Installing BlueCat Gateway as a Docker container - Platform - BlueCat Gateway - 24.3.1

Gateway Installation Guide
ft:locale
en-US
Product name
BlueCat Gateway
Version
24.3.1
Important:

You can set up BlueCat Gateway to authenticate with either BlueCat Address Manager (BAM) or Micetro, but not both.

If you are running Gateway on RedHat Enterprise Linux (RHEL), the installation procedure has many differences. For more details, see Installing BlueCat Gateway on RHEL with RHEL-compiled Docker or Podman.

When installing BlueCat Gateway, you will do the following:

  1. Acquire the Gateway image either from the Quay repository or as a download from Customer Care.

  2. If you're using custom certificates, set permissions for the workspace folder so that Gateway can access them.

  3. Run a Docker command to start the Gateway container. This command will be slightly different depending on your system needs and attributes.

Starting the container completes installation of BlueCat Gateway. Your next steps should be to go to Address Manager to create the BlueCatGateway UDF, set up BlueCat Gateway administrators, and add Gateway and users. For more details, see Additional Gateway setup when authenticating with BlueCat Address Manager.

Tip: For more information on Docker commands, see Common Docker commands.

1. Acquire the Gateway image:

To acquire the docker image, do one of the following:

  • To acquire the Gateway image from the public Quay repository:

    Download the Gateway application from Quay using the following command:

    docker pull quay.io/bluecat/gateway:24.3.1

  • To download the Gateway image from BlueCat Customer Care:

    If you need to download the Gateway image from a tar file, you can obtain it from BlueCat Customer Care. You can then copy the tar file to your host machine and use the docker load or podman load command to install the image.

    1. Download the v24.3.1.zip file from BlueCat Customer Care.

    2. Copy the file to the BlueCat Gateway host machine.

    3. From the Linux console of the BlueCat Gateway host machine, run the following command:

      docker load -i <Path to image tar file on host>

  • To acquire the Gateway image from a host behind a firewall:

    If your Linux host machine is behind a firewall, you must first pull the BlueCat Gateway image on a separate Linux machine with Internet connectivity, and then copy the image to the host machine.

    1. From the Linux console of a separate machine, run the following command to pull the BlueCat Gateway image from the public repository:

      docker pull quay.io/bluecat/gateway:24.3.1

    2. On that same (separate) machine, run the following command to save the Docker image as a .tar file:

      docker save -o <Path for the saved tar file> quay.io/bluecat/gateway

      Where <Path for the saved tar file> is the path and file name for the generated Docker image file.

    3. Copy the generated image file to the BlueCat Gateway host machine.

    4. From the Linux console of the BlueCat Gateway host machine, run the following command:

      docker load -i <Path to image tar file on host>

      Where <Path to image tar file on host> is the location on the host machine where you copied the generated image.

1. Custom certificates: Setting permissions for the workspace folder

Tip: If you're not using custom certificates, you can skip this section.

After acquiring the image, if you will be using custom TLS/SSL certificates with Gateway when authenticating with BlueCat Address Manager, you must set appropriate permissions for your workspace location on the Gateway host machine.

Specifically, you must set the ownership of the local workspace directory (listed as <Path to Gateway workspace> here) to either the user or the group under which Gateway runs. Which you use depends on how you organize your authentication accounts.

  • Setting ownership of the folder to the user: By default, Gateway runs under the flask user with UID 9000. Enable the following permissions for this user:

    chown -R 9000 <Path to Gateway workspace>
chmod -R u=rwx <Path to Gateway workspace>

  • Setting ownership of the folder to the group: By default, Gateway runs under the root group (with GID 0). Enable the following permissions for this group:

    chgrp -R 0 <Path to Gateway workspace>
chmod -R g=rwx <Path to Gateway workspace>

You can now start the Gateway container (see below).

Important: After starting the container, you must copy your custom certificate files to the host machine and set appropriate permissions such that Gateway can use them. Additional steps are listed below.

3. Start the Gateway container

To install the Gateway container, you will run a docker or podman command. You might need to add or change parameters in this command, depending on your system needs and attributes.

In particular, commands in the following procedure show how to set up BlueCat Gateway with BlueCat Address Manager authentication. If you want BlueCat Gateway to instead authenticate with Micetro, wherever it appears, change the BAM_IP environment option to set MICETRO_IP instead: 

-e BAM_IP=<BAM IP address or URL> \

should change to this option:

-e MICETRO_IP=<Micetro IP or URL> \
Note: Starting the container completes installation of BlueCat Gateway. Your next steps should be to go to Address Manager to create the BlueCatGateway UDF, set up BlueCat Gateway administrators, and add Gateway and users. For more details, see Additional Gateway setup when authenticating with BlueCat Address Manager.

By default, you can start Gateway with the following command:

docker run -d \
-p 80:8000 \
-p 443:44300 \
-v <Path to mapped workspace directory>:/bluecat_gateway/ \
-v <Path to mapped logs directory>:/logs/ \
-e BAM_IP=<BAM IP address or URL> \
--name bluecat_gateway quay.io/bluecat/gateway:24.3.1

Where:

  • <Path to mapped workspace directory>: The path to your desired location for the Gateway folder.

  • <Path to mapped logs directory>: The path to the location where you want to store Gateway log files.

  • <BAM IP address or URL>: The URL of the instance of BlueCat Address Manager.

Starting the container completes installation of Gateway. You can now finalize the Gateway setup:
Tip:

If you removed the Gateway container and are reinstalling it with the same BAM server IP, workspace, and logging directory: You do not need the environment variable (-e) that specifies the server address in the docker run command:

docker run -d \
-p 80:8000 \
-p 443:44300 \
-v <Path to mapped workspace directory>:/bluecat_gateway/ \
-v <Path to mapped logs folder>:/logs/ \
--name bluecat_gateway quay.io/bluecat/gateway:24.3.1

If you're using custom SSL certificates:

After starting the Gateway container, you must copy your certificate files to the host and assign permissions so that Gateway can access them. To do so:

  1. Create the folder /certificates/server in the workspace folder (<Path to Gateway workspace>):

    mkdir -p <Path to Gateway workspace>/certificates/server/

  2. Generate your custom SSL certificate files (.crt and .key), if you haven't already done so..

  3. Copy your custom SSL certificate files to the <Path to Gateway workspace>/certificates/server/ folder, renaming them to gateway.crt and gateway.key.

  4. Apply the same permissions that you set for the workspace earlier to the certificates folder. To do so, depending on whether you earlier set the ownership based on the user or the group under which Gateway runs, do one of the following.

    • If you set ownership of the <Path to mapped workspace> folder to the user: By default, Gateway runs under the flask user with UID 9000. Enable the following permissions for this user:

      chown -R 9000 <Path to Gateway workspace>/certificates
chmod -R u=rwx <Path to Gateway workspace>/certificates
    • If you set ownership of the <Local directory> folder to the group: By default, Gateway runs under the root group (with GID 0). Enable the following permissions for this group:
      chgrp -R 0 <Path to Gateway workspace>/certificates
chmod -R g=rwx <Path to Gateway workspace>/certificates

  5. Restart the Docker container.