Installing Db2 on macOS Using Docker

This is the first of a series of articles focused on setting up an Apple computer as a development environment for Db2 databases. The plan is to get the environment set up first, then some tools, and finally programming. The first step is installing Db2 using Docker.

Introduction

I have been using Apple computers as my primary platform for many years.
For most of those years, I had to maintain Linux/Windows virtual machines (using VMWare Fusion) in order to do much.
There was a brief period in 2009 when IBM provided a macOS implementation of Db2 Express-C v9.7 on Mac OS X, but many of the tools were not included and running a back-level version doesn't do much good over time.
So, even when I could run a native Db2 server on my machine, I still ended up maintaining a Linux instance as well.
With the upsurge of virtualization tools, it has become much easier to work with Db2 on macOS.

In this article, I'll go into how to set up and use Db2 using Docker on macOS. This is not the first article to cover Db2 on Docker, of course. Ian Bjorhovde wrote an excellent article for IDUG members. I plan to go a bit further and get this usable for development on macOS, but that seems ambitious, so I had better break it down into multiple articles. Let's start with getting macOS Docker Desktop set up and get Db2 running on it.

On macOS, Docker uses a Linux-based container. This makes it fairly simple to run any Linux application, program, or server process in its own container within the desktop environment. It also means we can use a Linux distribution of Db2.

IBM has thoughtfully provided a Db2 image on Docker Hub and they documented the use of Docker for installation of Db2 Community Edition in the IBM Knowledge Center. I’m using a modified version of the instructions for macOS found here.

This will only work on the current line of Intel-based Apple computers. I hope we will be able to manage something similar on the upcoming Apple Silicon based computers.

According to the IBM Knowledge Center documentation here the Db2 Community Edition Docker image has the following, preset limitations:

  • Requires macOS 10.10 or higher
  • Memory limit: 16GB
  • Core limit: 4 cores
  • Database size: 100GB

That will be more than enough for my development needs.

Preparation

If you have not already installed the macOS Docker Desktop application, go to https://www.docker.com/get-started and get started. Go ahead and create a Docker ID while you are there and set up Two Factor Authentication to keep your access secure.
You need the Docker ID to log into the Docker Hub and pull images. Of course, this would also allow you to create your own images and share them.

Installing Docker Desktop on macOS if pretty straightforward. You download the Docker Desktop disk image, open it, and drag the icon into the Applications folder. To start it, double-click the icon from the Applications folder and provide your administrator password if asked. After that, the Docker Desktop whale icon will live in the upper right menu bar.

Docker Settings

Ok, now that you have Docker Desktop up and running you can adjust some of its settings. Open the Docker Desktop Preferences and you'll get a window with a couple of tab-like sections. The default general settings are probably fine but there are resource settings we likely need to change.

Docker Settings

You'll want Docker to use only a subset of your system's resources, but you also want to make sure to allocate enough memory to run Db2 with decent performance. My system has 8 cores and 32GB, so I let Docker use up to half the cores and 8GB of memory.

Docker Advanced Settings

By default, Docker Desktop gives shared access to much of your macOS filesystem. I do not particularly want that. I want to keep Docker contained to specific locations. I remove the default locations and add a new one. But first, we have to create the folder. My preferred location is ~/Docker which expands to /Users/johnmaenpaa/Docker. This will be quick, go ahead and open a Terminal window and create that (and a few other) directories.

mkdir Docker
mkdir Docker/db2inst1
mkdir Docker/db2backup

Then, back in the Docker Desktop Preferences, add the new directory to the File Sharing list.

 Docker File Sharing

Ok, that part is done. Click on the Apply & Restart button and move on to the next step.

Docker Login

Logging into the Docker Hub gives you access to pre-defined Docker images, including Db2. You can log in using the Docker Desktop user interface, but I am going to go through the command line steps using a Terminal window. In the Terminal, you use the docker command to issue Docker commands.

First, we login using the docker login command.

Docker Login

And, that failed the first time thanks to my security settings. Taking a quick web browser trip to Docker Hub, there is a Security setting that will let me create a new Access Token.

Docker Security

Once that is created, copy the token and paste it in when the docker login command asks for a password.

Access Token

The messages from the docker command and the website make it fairly easy to get through this without a hassle. And, next time you will be able to docker login without needing to do this again. And for those of you worried that I just gave you my secure token, I have already deleted this one.

Db2 Docker Installation

You can find and review information about the Db2 docker image in the Docker Hub at https://hub.docker.com/r/ibmcom/db2.

Db2 Environment List

Earlier, we created directories to hold Db2 databases and backup files. Now, we need to set up a file with saved environment variables that will be used to set up the Db2 docker container.

Create ~/Docker/db2inst1.env_list file using your preferred editor, with content:

LICENSE=accept
DB2INSTANCE=db2inst1
DB2INST1_PASSWORD=mypasswd
DBNAME=dojo
BLU=false
ENABLE_ORACLE_COMPATIBILITY=false
UPDATEAVAIL=NO
SAMPLEDB=false
REPODB=false
IS_OSXFS=true
PERSISTENT_HOME=true
HADR_ENABLED=false
ETCD_ENDPOINT=
ETCD_USERNAME=
ETCD_PASSWORD=

There are several options in this file you should take note of:

  • We all know that storing passwords in plain text isn’t the best idea, so we will modify the password in a later step.
  • The DBNAME is set to dojo because I want a DOJO database created. If you do not want a database created, leave it blank.
  • The SAMPLEDB is set to false because I do not want a SAMPLE database created when Db2 is first started. To let the SAMPLE database be created as part of the instance startup, set the option to true. The Db2 documentation incorrectly lists this as TO_CREATE_SAMPLEDB.
  • The UPDATEAVAIL is set to YES to avoid having to change it later. According to the documentation it should be set to NO because we are doing an initial installation and the instance does not need to be updated to a new software level. I have tried it both ways for the initial creation of the container and have not noticed a difference.

Get Db2 Docker Images

You can find and review information about the Db2 docker image in the Docker Hub at https://hub.docker.com/r/ibmcom/db2. Back in our Terminal, do the following to download the Db2 image.

docker login
docker pull ibmcom/db2

This will take a little while.

Docker Pulling Db2

Eventually, it will finish and you will be ready to move on to the next step.

Docker Pulled Db2

Run Db2 Docker - First Time

Open up your Terminal window and change to the ~/Docker directory and double check that we have created our subdirectories.

cd ~/Docker
ls -al

Now we run the Db2 server in a new Docker container. This is a single command, so make sure cut/paste handles that correctly. If you chose a different location for your files then you'll need to customize this command to specify your directory locations.

docker run -h db2inst1 --name db2inst1 --restart=unless-stopped  \
--detach --privileged=true -p 50000:50000 -p 55000:55000 \
--env-file ~/Docker/db2inst1.env_list \
-v ~/Docker/db2inst1:/database \
-v ~/Docker/db2backup:/backup \
ibmcom/db2

You should see something like the following. In this particular run, I used --restart=always but have since switched to using
--restart=unless-stopped to avoid having the Db2 server instance running when I'm not using it.

Docker Run Db2]

Now we have a container up and running with a Db2 instance in it. Let's double check inside the container by opening up a shell.

docker exec -ti db2inst1 /bin/bash

ps -ef

This started up a root session inside the running container. We can do a lot of things from here and we can see that Db2 is up and running, but we are not done yet.

Post Installation Steps

Now that we have our Db2 instance up and running, we have a couple of post-installation steps that will make life better in the long run.

DB2INST1 Password Settings

We need to set a new password for the db2inst1 userid inside the container and we need to make it non-expiring so that we don't have to fiddle with it later. We do this from a root shell in the container.

docker exec -ti db2inst1 /bin/bash
chage -M -1 db2inst1
passwd db2inst1

db2inst1 password

If necessary, you can come back and change the password again later because we are able to get into the root user without needing a password. We can also switch to the db2inst1 user and create databases, issue Db2 commands, or do pretty much any database maintenance we need.

su - db2inst1
db2sampl
db2 list database directory
db2 create database dojo

Db2 Connect Dojo

Modify Your Settings File

You may want to modify your db2inst1.env_list file after the initial run, but with the options I have set this is not necessary. This file is only used when we specify it on the docker run command.

Operational Concerns

Stopping and Starting Db2

You can stop, start, or restart the db2inst1 container from the command line.

docker stop db2inst1
docker start db2inst1
docker restart db2inst1

Or you can control it from the Docker Desktop UI.

Docker Desktop db2inst1

Remove the Container

Everything we have done so far is repeatable. You can tear it down and do it again.

In a Terminal window:

docker stop db2inst1
docker rm db2inst1

Then remove the contents of the ~/Docker/db2inst1 directory if you want to delete the instance data (including any databases that were created).

rm -rf ~/Docker/db2inst1/*

Before you re-create the Db2 container, make sure your db2inst1.env_list file has the correct settings for a new instance if you made any changes.

Open Firewall ports

If you want to connect to your Docker-based Db2 instance from a second computer, you may need to open up the ports in your firewall. My firewall options look like this:

Firewall Ports

The firewall settings are available in System Preferences within the Security & Privacy settings. There is a tab for the "Firewall". If the firewall is started, the Firewall Options button will be available.

Db2 Instance Files

When we issued the docker run command, we mapped the ~/Docker/db2inst1 directory to the container's /database directory. Inside the container, Db2 uses this directory to store its instance and database files. Here is the view of those files from macOS (outside of the container).

Db2 Instance Files on macOS

Upgrade Db2

When a new fixpak level for Db2 becomes available, you can upgrade your Docker installation using the following steps:

First, re-pull the Docker Db2 image. If there is no newer image then it will tell you. If there is a new image, you'll see something like:

docker pull ibmcom/db2
Using default tag: latest
latest: Pulling from ibmcom/db2
524b0c1e57f8: Pull complete
e7a9171c839a: Pull complete
f4447742b873: Pull complete
db90696d3502: Pull complete
6acc1312ab24: Pull complete
67e9a72bc07a: Pull complete
2b9e6b7678c7: Pull complete
Digest: sha256:cf95dd272a4f99d7f9119945ecad04b64ad3a2badc8a6682f1105aa87279da60
Status: Downloaded newer image for ibmcom/db2:latest
docker.io/ibmcom/db2:latest

Second, make sure you have UPDATEAVAIL=YES in your db2inst1.env_list file. This way Db2 will upgrade the existing instance.

Third, stop your db2inst1 container and destroy it, but do not touch the contents of your ~/Docker/db2inst1 directory. When you run the docker container ls command, the hexadecimal container number listed is the one you need to use for the docker container rm command.

docker stop db2inst1
docker container ls
docker container rm xxxxxxxx

Fourth, Use the docker run command to create and run a new Db2 container.

docker run -h db2inst1 --name db2inst1 --restart=unless-stopped \
--detach --privileged=true \
-p 50000:50000 -p 55000:55000 \
--env-file ~/Docker/db2inst1.env_list \
-v ~/Docker/db2inst1:/database \
-v ~/Docker/db2backup:/backup \
ibmcom/db2

Fifth, do the Post Installation Steps to set your db2inst1 password. This is necessary because the Linux system is part of the container and we deleted all of its content.

Your db2inst1 instance should now be running on the new level of Db2 without having done backup/restore operations on our databases.

Using Db2 in Its Docker Container

You can get to a Linux shell and manage your instance as the db2inst1 instance owner using the following command in a Terminal window. If you do this often enough, you may want to set up a command alias that will be easier to remember.

docker exec -ti db2inst1 /bin/su - db2inst1

This essentially opens an interactive terminal session with the container and runs the /bin/su command in that session. The session initially connects with the root user and this command invokes a shell using our db2inst1 instance owner user. That interactive shell executes the standard .bash_profile and .bashrc files that are normally defined within the home directory for instance owners on Linux systems. These, in turn, execute the db2profile shell script that sets up the Db2 environment. You now have the normal commands available for a Db2 instance.

Database Backups

We are setting up a development environment, but there is a chance that we would want to be able to restore our database or move it elsewhere. You can use the standard db2 backup db command inside the container when in a shell as the db2inst1 instance owner.

db2 deactivate database sample
db2 backup db sample to /backup without prompting

Remember that second directory, db2backup that I created earlier? The docker run command mapped this to the /backup directory inside the container. The db2 backup command here places the backup file in that directory. Now, we can treat that database backup as a portable file and have a safe backup of our database.

db2 backup database

Conclusion

We've installed Db2 running on Docker on macOS. You can learn more about Docker Desktop on macOS here. Within the Docker container, you can operate your Db2 instance as if it was running on a normal Linux system.

Recent Stories
Db2 Client Packages

INDEX COMPRESSION in Db2 Z, A recap and overview!

Quick Guide to Compression for Db2 Column-Organized Tables