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

Important:

You can set up BlueCat Gateway to authenticate with BlueCat Address Manager (BAM), Micetro, or using standalone authentication without connecting to either server type. You can use only one authentication platform.

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:

Acquire the Gateway image either from the Quay repository or as a download from Customer Care.
If you're using custom certificates (with BlueCat Address Manager), set permissions for the workspace folder so that Gateway can access them.
Run a Docker command to start the Gateway container. This command will be slightly different depending on your system needs and attributes and on which authentication platform you're using.

Starting the container completes installation of BlueCat Gateway. Your next steps depend on what you're authenticating Gateway with.

If you're authenticating with BlueCat Address Manager, go to Address Manager to create the BlueCatGateway UDF, set up BlueCat Gateway administrators, and add Gateway users. For more details, see Additional Gateway setup when authenticating with BlueCat Address Manager.
If you're authenticating with Micetro, go to Micetro to set up the users and roles. For more details, see Additional Gateway setup when authenticating with Micetro.
If you're using standalone authentication (not connecting to either of Address Manager or Micetro), you might need to set up Standalone authorization functions to allow for multiple user accounts. For more details, see Custom authentication functions for Standalone authentication in the Gateway Administration Guide.

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:25.1.0
```
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 v25.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:25.1.0
```
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.

2. Custom certificates: Setting permissions for the workspace folder

Tip: If you're not using custom certificates, or you are not authenticating with , 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 and start the Gateway container, you will execute a docker or podman run command. You will need to add or change parameters in this command, depending on your system needs and attributes. After executing the command, Gateway starts automatically and you can can log in to it by browsing to its URL or IP address.

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/ \
<Authentication platform environment variables> \
--name bluecat_gateway quay.io/bluecat/gateway:25.1.0

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.
<Authentication platform environment variables>: Environment variable settings specific to the platform you're authenticating with (Address Manager, Micetro, or using standalone authentication). Use variables from only one authentication platform.

Authentication platform environment variables are as follows:

Setting Description

Setting	Description
BlueCat Address Manager	Replace `<Authentication platform environment variables>` with the following: `-e BAM_IP=<BAM IP address or URL> \` Where `<BAM IP address or URL>` is the URL of the instance of the Address Manager server that you want to connect to. 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 to set this environment variable 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:25.1.0`
Micetro	Replace `<Authentication platform environment variables>` with the following: `-e MICETRO_IP=<Micetro IP or URL> \` Where `<Micetro IP or URL>` is the URL of the instance of the Micetro server that you want to connect to.
Standalone authentication	Replace `<Authentication platform environment variables>` with the following: `-e AUTHENTICATION=STANDALONE \ -e STANDALONE_USERNAME=<Standalone account user name> \ -e STANDALONE_PASSWORD=<Standalone account password> \` Where: `<Standalone account user name>`: The username for the account that Gateway will set up for standalone access. `<Standalone account password>`: The password for the account that Gateway will set up for standalone access. During installation, Gateway will set up a single user account with the indicated password. This account will be assigned to the admin group, with access to all Gateway features, workflows, and functionality. Credentials for this account will be stored in the docker container environment. For more details about password conventions and valid characters for this username and passord, see Standalone authentication username and password format. For more details about Standalone authentication in general, see About Standalone authentication installations.

BlueCat Address Manager

Replace <Authentication platform environment variables> with the following:

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

Where <BAM IP address or URL> is the URL of the instance of the Address Manager server that you want to connect to.

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 to set this environment variable 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:25.1.0

Micetro

Replace <Authentication platform environment variables> with the following:

-e MICETRO_IP=<Micetro IP or URL> \

Where <Micetro IP or URL> is the URL of the instance of the Micetro server that you want to connect to.

Standalone authentication

Replace <Authentication platform environment variables> with the following:

-e AUTHENTICATION=STANDALONE \
-e STANDALONE_USERNAME=<Standalone account user name> \
-e STANDALONE_PASSWORD=<Standalone account password> \

Where:

<Standalone account user name>: The username for the account that Gateway will set up for standalone access.
<Standalone account password>: The password for the account that Gateway will set up for standalone access.

During installation, Gateway will set up a single user account with the indicated password. This account will be assigned to the admin group, with access to all Gateway features, workflows, and functionality. Credentials for this account will be stored in the docker container environment.

For more details about password conventions and valid characters for this username and passord, see Standalone authentication username and password format.

For more details about Standalone authentication in general, see About Standalone authentication installations.

Starting the container completes installation of Gateway. You can now finalize the Gateway setup. For more details, see sections under Additional setup.

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:

Create the folder /certificates/server in the workspace folder (<Path to Gateway workspace>):
```
mkdir -p <Path to Gateway workspace>/certificates/server/
```
Generate your custom SSL certificate files (.crt and .key), if you haven't already done so..
Copy your custom SSL certificate files to the <Path to Gateway workspace>/certificates/server/ folder, renaming them to gateway.crt and gateway.key.
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
```
Restart the Docker container.

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

Gateway Installation Guide

1. Acquire the Gateway image:

2. Custom certificates: Setting permissions for the workspace folder

3. Start the Gateway container