Installing SAP Cloud Connector into Docker and connecting it to SAP Cloud Platform

UPDATE: Meanwhile, SAP has published a docker image for ABAP, for details see SAP ABAP Platform 1909, Developer Edition: AVAILABLE NOW. It contains a SAPCC as well.

A little late, but here I am with the second part of the series. In case you prefer a fast-forward you can watch the YouTube video or scroll down to “Installing the SAPCC into Docker” and execute the four commands to get the job done. Otherwise, continue reading this kinda exhaustive blog which turns out to mainly explain things not really mentioned in the video.

• Part 1: ABAP is here and it stays in the DNA of SAP even in the New Age of SAP Development
• Part 2: Installing SAP Cloud Connector into Docker and connecting it to SAP Cloud Platform
• Part 3: Installing SAP NW ABAP into Docker
• Part 4: Configure SAPCC + NW ABAP for Principal Propagation + Docker Network config for both Containers
• Part 5: SAPCC, NW ABAP, SAPCP config for the Identity Provisioning Service to sync users from ABAP to SAPCP

You can follow all the blogs of the series on your own laptop without getting charged at all. I used my maxed-out 2017 MacBook Pro (2 TB SSD, 16 GB RAM, Intel i7 (7820HQ) Kaby Lake 2.9 GHz), but you can use Win 10 or some Linux as well (Docker is the common denominator we need). For this blog 8 GB of RAM should be enough but starting from Part 3 I suggest you have at least 16 GB RAM (I did not try with less than 16 GB). The Dockerfile in this blog is based on this one.

Resources

• YouTube: https://www.youtube.com/watch?v=9uU1ny-0iNE
• GitHub: https://github.com/nzamani/sap-cloud-connector-docker

What you will have at the end of this blog (Goal)

At the end of this blog you will have a running SAP Cloud Connector (SAPCC) installed on your own laptop inside a Docker container. It will connect to an SAP Cloud Platform (SAPCP) account, for example to your own trial account, using your credentials. The green arrow in the image above is important, because it’s always the Cloud Connector that opens the steady connection (= the “tunnel”). It’s never the SAPCP that opens that steady connection to your SAPCC on your laptop, or in real life to your companies SAPCC running behind the firewall.

In less than 7 minutes my YouTube video (see above) shows you exactly how to install the SAPCC into Docker and connecting it to the SAPCP afterwards, for example to your very own SAPCP trial account. The GitHub repo linked above is used in the video and it contains additional details. Having the mentioned resources actually makes this blog useless unless I add information not mentioned in the resources. Now let’s start by discussing why the SAPCC is so important.

What is the SAPCC and why is it so important?

In short for ABAP developers, the SAPCC is the component that opens the doors for your on-premise NW ABAP to be part of the new age SAP development with SAPCP. Typically, this happens by offering on-premise OData services or RFCs accessible by Fiori/SAPUI5 apps or SAPCP services running on SAPCP. ABAP developers might need to configure the mappings inside the SAPCC, or they ask someone else to handle the needed configuration (covered by the other blogs of the series).

For Fiori developers on SAPCP, the SAPCC is the magic that happens behind the scenes when their Fiori/UI5 apps use SAPCP destinations connected to a given backend to call OData services (assuming “Fiori developer” is defined as doing only frontend coding, which is often not a correct definition). Typically, they don’t really know much about the SAPCC, for them it always looks like they are calling some OData service using an SAPCP destination.

For architects and admins, the SAPCC is needed to configure (some) SAPCP services, destinations, or apps, and to control which backend resources are accessible from the SAPCP. They also take care of certificates and other administrational tasks related to SAPCC.

These PoVs of the personas used above are not 100% correct and not the only ones, but as an oversimplified abstraction they should give you a first idea. For example, sometimes a single person can do all the jobs mentioned above, and in this blog series we will basically do (almost) all of the jobs. Could the be your first step to becoming a full-stack developer? 🙂

So, we know now that the SAPCC is the key to do cloud development with your on-premise ABAP, and that works even today prior to the release of ABAP in the Cloud. That also means all your ABAP experts can join cloud development now – yes you can! But what exactly does it mean: “The SAPCC connects to the SAPCP”?

How SAPCC connects to SAPCP accounts behind the scenes

After having configured your SAPCC to connect to your SAPCP account the SAPCC will open a (steady) WebSocket-based connection to that SAPCP account using the credentials you offered. In other words, the endpoint of the WebSocket is your SAPCP account. This WebSocket-based connection is referred to as secure tunnel (SSL/TLS) and it goes through your firewall to the SAPCP. The requests from the SAPCP account going to your on-premise ABAP (i.e. OData calls via destinations) are piped through the open WebSocket (let’s ignore the destinations in this first blog). How do I know it’s a WebSocket-like connection? I never saw any documentation about this, so I derived this by exploring the SAPCC log files. Probably there are multiple WebSockets created, but there is always at least one open WebSocket, and is the WebSocket closes the SAPCC re-opens it again automatically. You configure your connections in the SAPCC UI as of 2.11 (in your browser). The official documentation states:

In general, the Cloud Connector tunnel is multiplexing multiple virtual connections over a single physical connection. Thus, a single connection can handle a considerable amount of traffic.

That’s a perfect description, isn’t it? I believe there must also be some sub-protocol sent over WebSocket (maybe something like STOMP, most probably something more lightweight). In fact, we don’t have to worry about this, for us it’s a black-box and that’s absolutely fine (I was just a little curious).

I assume opening/multiplexing WebSockets through through those WebSockets connections can be quite complex. Maybe that’s a reason why there is no support for WebSocket connections from your SAPCP Fiori apps to your NW ABAP through SAPCC (WebSockets are not supported as noted under Features in the SAPCC FAQ)! If you don’t believe that try on your own and check two Fiori Launchpads (FLP), one on SAPCP and the other one on your on-premise ABAP. Make sure to configure everything needed for receiving Notifications in the two FLPs. While your on-premise FLP will use WebSockets your SAPCP FLP will only use polling (i.e. every 60 seconds the FLP sends a request to NW ABAP to check for notifications)!

For additional details have a look at the official documentation (that documentation is really good!):

• SAP Cloud Connector Documentation Start Page
• SAPCC Configuration & Setup
• On-Demand To On-Premise Connections
• SAPCC Initial Configuration

What is Docker and why is it important for SAP Developers?

In the last years containers have become very popular. There is a lot happening around containers, and cloud infrastructures often use containers behind the scenes; but there are other use cases as well. As one of the most popular representatives of container technologies Docker has been around now for about 5-6 years. While non-SAP developers have been using Docker for years I have only rarely seen SAP developers using Docker.

Docker can be used for many use cases. The official Docker website lists some of them (just as a good start), so there’s no need to repeat them here. In simple words:

Docker is a tool that simplifies creating, deploying, and running container-based applications. Often, we call such applications containerized applications.

A container is typically a pre-packaged application including all of its dependencies. Docker makes it easy to create such containers. Container technology, or simply containers, are actually nothing new. It all started more than thirty years ago with Unix and the idea of process isolation. Have look at A Brief History of Containers: From the 1970s to 2017 (what a nice blog!) for an interesting overview of container history. You could also say Docker makes is easy to use Unix technology – even on Windows. Docker is heavily used for DevOps, for MicroServices, it allows reproducible deployments, and it comes in handy for scaling. This is not a Docker blog, so we won’t go deeper into the details – although there is actually a lot more we could add. Maybe continuing to read What Is Docker? is good start.

Often, Docker is compared to virtual machines. However, Docker containers are way more lightweight and more portable (well, containers in general). Lots of companies have moved their server applications from VMs to containers, and I bet lots of them are powered by Docker. But what benefits do I have as an SAP developer, maybe as a native SAP developer with ABAP experience who wants to step into the new age of SAP development with SAPCP (*wink wink*)?

Well, first of all I believe everybody should have some basic Docker know-how. It’s too important for neglecting it. The prediction is that later this year, when ABAP in the Cloud gets published, you will be able to implement ABAP MicroServices for the SAPCP, and I guess Docker will be in some way involved here (sooner or later). But even without ABAP in the Cloud, it’s only a matter of time that Docker will become more and important for SAPCP development. When asking “What does Cloud Native mean?”, then some people even answer “When it runs in a container”. In other words: you can’t do anything wrong learning Docker! Secondly, and that’s how we will use Docker in this blog series, Docker allows you to install and run software without worrying too much about whether that software could harm your laptop. The following image tries to explain this in a simple and abstracted way (without claiming to be complete):

The message is hopefully clear: if you install software directly on OS level then a virus could harm your system. Furthermore, installed software could potentially pollute your OS. In contrast, using isolated containers can help to makes sure that your OS is not polluted. Additionally, a virus you might have in one container cannot escape that container (yes, there are exceptions). In this blog series we will install both SAPCC and NW ABAP into Docker. Thanks to Docker containers everything we do is portable; the containers run on Win 10, macOS, and Linux. And that raises the question of how to create a Docker Container?

Docker Basics

Docker containers are created from Docker images. A Docker image can be considered as some kind of a template for creating a container. The Docker image itself is built from a so called Dockerfile. A Dockerfile contains a sequence of commands executed on the CLI to assemble a Docker image; the build can be automated. In this blog our Dockerfile installs the SAPCC after all dependencies of the SAPCC have been installed. Once a Docker image has been built it can be used to create containers based on the image. In our case, we’ll first create a SAPCC image, then we’ll create a SAPCC container from that images.

A Dockerfile typically declares a base image (we’ll neglect creating images from scratch). Our base image for the SAPCC image is CentOS, which has currently a size of about 200 MB (together with Ubuntu one of my favorite Linux distributions). There are base images from about 1 MB up to hundreds of MB; from a minimum Linux up to full blown Linux. We use CentOS, thus we use yum to install some dependencies before we can download and install both SAPCC and the SAP JVM.  After having installed the SAPCC from the downloaded rpm file we need to stop the SAPCC! Why is that?

Docker containers are based on Process ID 1 (PID 1); the root process, which should be your applications process! This one process is started when the container gets started, and it’s stopped when the container is stopped. If that process dies, then the container is stopped. Read The importance of PID 1 in containers for some insights. For us it’s important to set the command that boots our SAPCC as the one that gets PID 1. This is achieved by the last CMD in the Dockerfile.

To give you an example of what PID 1 means simply try to restart the SAPCC from the Web UI (which you will see if you follow this blog). After pressing the restart button nothing seems to happen, but why? That’s because the PID 1 was stopped from the Web UI, and that stops the container immediately because PID 1 has gone. As a result, you cannot restart the by pressing the restart button.

There’s a lot more to say about Docker, but as I already mentioned this is rather a simplified fast-forward overview of Docker than a blog about Docker. Now let’s create a Docker image and then a container. However, keep in mind that this setup is only for dev purposes. In fact, there is a lot configuration needed to make the SAPCC run the way we want it to run (covered in the other blogs of the series). In a perfect Docker container world, we would add all the config steps into the Dockerfile so that no manual steps would be needed anymore. But that was not the goal of this blog because I want everyone being able to follow and see things in action. Docker is just a tool I use on the path to Seeing is Understanding.

And yes, Docker containers have created challenges we didn’t have earlier. For example, how to make sure all your containers always have the latest patches installed? Well, there are tools for that… Again, that’s out of scope here, but google helps a lot here…

Installing the SAPCC into Docker

After having installed both Docker and git on your machine fire up your favorite terminal (on Windows I suggest GitBash) and execute the following commands (details):

# Clone the repo containing the Dockerfile
git clone https://github.com/nzamani/sap-cloud-connector-docker.git
cd sap-cloud-connector-docker

# Build the Docker image
docker build -t sapcc:2.11.0.3 .

# or if you are behind a proxy:
docker build --build-arg http_proxy=http://proxy.mycompany.corp:1234 --build-arg https_proxy=http://proxy.mycompany.corp:1234 -t sapcc:2.11.0.3 .

# Then create a container running in detached mode
docker run -p 8443:8443 -h mysapcc --name sapcc -d sapcc:2.11.0.3

As you can see, we chose the Docker image we built to be named sapcc, and additionally we give it a tag 2.11.0.3. I typically use the version of the installed SAPCC as the tag so that I can clearly see what version of SAPCC a certain Docker image contains.

Using docker run we create and run a container called sapcc in detached mode (-d). The container is derived from our Docker image created in the previous step. I chose to set the hostname of that container to mysapcc. Per default the SAPCC uses port 8443 for its Web UI (https). Thus, the Dockerfile exposes the same port 8443. However, it would not be available on the container’s host (i.e. your laptop) without publishing it. This is achieved with the option -p 8443:8443 which is basically telling Docker to make (“publish”) the exposed port 8443 (second port) available on the host under port 8443 (first port). In other words, if you access port 8443 on the host (first port) then this maps to port 8443 inside the Docker container (second port).

After the command sequence above you have a container running a clean installation of the SAPCC. You can now access your SAPCC running inside the container by going to https://localhost:8443/ in your favorite browser. Please watch the video to learn how to connect it to your SAPCP account. The YouTube video illustrates the whole process from cloning the git repo, to building the Docker image and running a container based on the image. After that you’ll see how to connect your SAPCC to your SAPCP account using your browser.

By the way, SAPCC is implemented with Java. Running Java inside Docker can have some limitations. Read Java and Docker, the limitations to find out more.

What versions of SAPCC and SAP JVM are used?

At the time of recording and writing the latest version of SAPCC was 2.11.0.3, thus this blog uses 2.11.0.3 everywhere, i.e. to tag the created Docker image. The latest version of SAP JVM was 8.1.035.

Please check my GitHub repo to find out which version of SAPCC and SAP JVM is used. You could also check this inside the Dockerfile itself; there you could simply search for the LABELs com.nabisoft.sapcc.version and com.nabisoft.sapcc.sapjvm.version, then check the assigned versions. In case your docker build command fails because the SAPCC and/or SAP JVM cannot be downloaded please open an issue for me on GitHub and I’ll have a look at it (most probably I need to update some URLs inside the Dockerfile). Keeping the tag for the Docker image in sync with the installed version of SAPCC makes sens. However, choosing something different works as well; just make sure you’re not getting confused because of the tags you choose.

Useful Docker commands

On the CLI you could list all your containers including some details by executing the following command:

docker ps -a

Without the option -a you would only see a list of running containers. If you run the same docker run command from above again, you will get an error because you can’t use the same container name again as long as there is a container with the same name. In that case you would have to stop the container first before you can remove and create it again with the same name:

# stop a container by name
docker stop sapcc

# remove a container by name
docker rm sapcc

# create and run the container again
docker run -p 8443:8443 -h mysapcc --name sapcc -d sapcc:2.11.0.3

Sometimes you want to test a few things right quick and you want to make sure the container gets removed after it is stopped. This you can achieve by adding the option –rm. Keep in mind that creating and running a new container with a published port on your host that is already in use will fail starting (but it is created). Thus, you could publish your container’s port on your host to a free port, i.e. to 8444:

# published port on localhost is 8444 + container is removed automatically
docker run -p 8444:8443 -h mysapcctest --name sapcctest --rm -d sapcc:2.11.0.3

Note that I’ve also chosen another hostname. After this command you can access another clean installation of SAPCC running inside another isolated container by going to https://localhost:8444/ in your browser. However, this time when stopping the new container via docker stop sapcctest you will see that it’s not listed anymore after executing docker ps -a. That’s because we added –rm to docker run.

In case you don’t really care how the exposed port(s) of your container are published on your host the option -P comes in pretty handy:

# Publish all exposed ports to the host interfaces using '-P'
docker run -P -h mysapcctest --name sapcctest --rm -d sapcc:2.11.0.3

Using this option makes sure that all exposed ports are published to your host. Executing one of the following command allows you to check how they are published to your host:

[~]$docker ps -a
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS                     PORTS                     NAMES
81e69ee8f2bc        sapcc:2.11.0.3      "/bin/sh -c '/opt/sa…"   5 seconds ago       Up 3 seconds               0.0.0.0:32768->8443/tcp   sapcctest
[~]$

[~]$ docker port sapcctest
8443/tcp -> 0.0.0.0:32768
[~]$

The first command shows the port mapping(s) from the PoV of your host. In our case  0.0.0.0:32768->8443/tcp means localhost:32768 is mapped to the exposed port 8443 of your container. The second command shows the port mapping(s) from the PoV of the container. In our case 8443/tcp -> 0.0.0.0:32768 means the exposed port 8443 is accessible on port 32768 on the container’s host. As you can see both are actually the same, only the PoV is mixed.

Starting an existing but currently stopped container is fairly simple:

# starting a container by name
docker start sapcc

Once the container is started you may want to open a shell to it using the root user. This can be achieved as follows:

# open a bash with root to the running container
docker exec -it -u root -w /root sapcc /bin/bash

Exploring the Docker images you have on your host is as easy as executing

# explore existing docker images
docker images

in your terminal. In case you want to remove an existing image, i.e. to free some space, simply execute

# delete image using image name + tag
docker image rm sapcc:2.11.0.3

or

# delete image by image id as received by 'docker images', i.e.:
docker image rm 0542592f22d7

in your CLI. However, this command will fail if you still have containers derived from the image you are trying to remove (no matter if they are running or not). In such cases you would remove the corresponding containers first before you can remove the image.

Last but not least: it’s quite easy backup an existing container. This is equal to creating a Docker image from an existing Docker container:

# Suggestion: stop the container you want to backup before continuing
docker stop sapcc

# create an image "sapccbackup" from the container "sapcc"
docker commit sapcc sapccbackup:1

# later you can create a new container from the new image "sapccimage"
# Hint: if the ports etc are already used by other containers you must 
# use different ports (or i.e. stopping the other containers first)
docker run -p 8443:8443 -h mysapcc --name sapccNewContainer -d sapccbackup:1

Now it’s time to play around with Docker; stop the containers, restart them, remove them, create some images and remove them,… That’s the best you can right now before you’ll see how to install NW ABAP in the next part of this blog series.