Downloading the IBM Db2 REST Service from the IBM Cloud Container Registry

The IBM® Db2 REST service container is hosted on the IBM Cloud® Container Registry.

About this task

Before downloading the REST service container, you need to configure your system to access the IBM Cloud Container Registry.

Procedure

  1. If you require an IBM Cloud account, go to the IBM Cloud registration page to create an account.
  2. Go to Getting started with the IBM Cloud CLI on the IBM Cloud Docs page for instructions on how to install the IBM Cloud command line tools.
  3. Log in to the container registry:
    1. From the command line, run ibmcloud login -a cloud.ibm.com -sso.
    2. Authenticate using the one-time code and select your account. Skip the region selection step.
    3. Run ibmcloud cr region-set global.
    4. Run ibmcloud cr login.
  4. Run docker pull icr.io/obs/hdm/db2rest:latest-amd64 to pull the container image.
  5. Run the command appropriate for your operating system to run the container.
    For Linux:
    docker run -it --net=host -e LICENSE=view --name=db2rest icr.io/obs/hdm/db2rest:latest-amd64
    For Windows and Mac OS X:
    docker run -it --hostname <Your REST server hostname> -p 50050:50050 -e LICENSE=view --name=db2rest icr.io/obs/hdm/db2rest:latest-amd64

    Locking the Db2 REST server to a single Db2 instance

    In order to execute commands against the Db2 REST server, you must request an authentication token. This request requires connection information for Db2. A single Db2 REST server can communicate with any number of Db2 instances but in some environments, the administrator may prefer that the server communicates with a single Db2 instance. In order to lock the Db2 REST server against a specific Db2 you can specify these environment variables to the docker run command instead of using the syntax in procedure step 5. You can choose which entries you wish to lock, for example you may exclude the database name if you want to allow the user to specify their database, while locking the database hostname, port and TLS connection information.
    DB2REST_DBHOSTNAME The hostname of the database
    DB2REST_DBPORT The database listener port (for example, 50001)
    DB2REST_SSLCONNECTION Whether the port identifies an TLS connection (true) or does not (false)
    DB2REST_DBNAME The name of the database (for example, BLUDB)
    DB2REST_SSLKEYSTOREPATH The fully qualified TLS keystore path within the Db2 REST container
    DB2REST_SSLKEYSTASHPATH The fully qualified TLS keystash path within the Db2 REST container

Example

For Linux:
docker run -it --net=host -e DB2REST_DBHOSTNAME=mydb2.hostname.com 
-e DB2REST_DBPORT=50001 -e DB2REST_SSLCONNECTION=true -e DB2REST_DBNAME=TESTDB -e DB2REST_SSLKEYSTOREPATH=/opt/ibm/dbrest/ssl/server.kdb 
-e DB2REST_SSLKEYSTASHPATH=/opt/ibm/dbrest/ssl/server.sth-e LICENSE=view --name=db2rest icr.io/obs/hdm/db2rest:latest-amd64
For Windows and Mac OS X:
docker run -it --hostname <Your REST server hostname> -p 50050:50050 -e DB2REST_DBHOSTNAME=mydb2.hostname.com 
-e DB2REST_DBPORT=50001 -e DB2REST_SSLCONNECTION=true -e DB2REST_DBNAME=TESTDB -e DB2REST_SSLKEYSTOREPATH=/opt/ibm/dbrest/ssl/server.kdb 
-e DB2REST_SSLKEYSTASHPATH=/opt/ibm/dbrest/ssl/server.sth-e LICENSE=view --name=db2rest icr.io/obs/hdm/db2rest:latest-amd64

Setting token expiry at the server level

The request for authentication accepts an expiry time. In some environments, the administrator may prefer a fixed value. Add the following to the docker run command to specify a fixed expiry:
-e DB2REST_EXPIRY=30m