SOA Suite 12c in Docker containers. Only a couple of commands, no installers, no third party scripts

For developers, installing a full blown local SOA Suite environment has never been a favorite (except for a select few). It is time consuming and requires you to download and run various installers after each other. If you want to start clean (and you haven’t taken precautions), it could be you have to start all over again.

There is a new and easy way to get a SOA Suite environment up and running without downloading any installers in only a couple of commands without depending on scripts provided by any party other than Oracle. The resulting environment is an Oracle Enterprise Edition database, an Admin Server and a Managed Server. All of them running in separate Docker containers with ports exposed to the host. The 3 containers can run together within an 8Gb RAM VM.

The documentation Oracle provides in its Container Registry for the SOA Suite images, should be used as base, but since you will encounter some errors if you follow it, you can use this blog post to help you solve them quickly.

A short history

QuickStart and different installers

During the 11g times, a developer, if he wanted to run a local environment, he needed to install a database (usually XE), WebLogic Server, SOA Infrastructure, run the Repository Creation Utility (RCU) and one or more of SOA, BPM, OSB. In 12c, the SOA Suite QuickStart was introduced. The QuickStart uses an Apache Derby database instead of the Oracle database and lacks features like ESS, split Admin Server / Managed Server, NodeManager and several other features, making this environment not really comparable to customer environments. If you wanted to install a standalone version, you still needed to go through all the manual steps or automate them yourself (with response files for the installers and WLST files for domain creation). As an alternative, during these times, Oracle has been so kind as to provide VirtualBox images (like this one or this one) with everything pre-installed. For more complex set-ups Edwin Biemond / Lucas Jellema have provided Vagrant files and blog posts to quickly create a 12c environment.


One of the benefits of running SOA Suite in Docker containers is that the software is isolatd in the container. You can quickly remove and recreate domains. Also, in general, Docker is more resource efficient compared to for example VMWare, VirtualBox or Oracle VM and the containers are easily shippable to other environments/machines.


Docker has become very popular and there have been several efforts to run SOA Suite in Docker containers. At first these efforts where by people who created their own Dockerfiles and used the installers and responsefiles to create images. Later Oracle provided their own Dockerfiles but you still needed the installers from and first build the images. The official Oracle provided Docker files can be found in GitHub here.

Container Registry

Oracle has introduced its Container Registry recently (the start of 2017). The Container Registry is a Docker Registry which contains prebuild images, thus just Dockerfiles. Oracle Database appeared, WebLogic and the SOA Infrastructure and now (May 2018) the complete SOA Suite.

How do you use this? You link your OTN account to the Container Registry. This needs to be done only once. Next you can accept the license agreement for the images you would like to use. The Container Registry contains a useful description with every image on how to use it and what can be configured. Keep in mind that since the Container Registry has recently been restructured, names of images have changed and not all manuals have been updated yet. That is also why you want to tag images so you can access them locally in a consistent way.

Download and run!

For SOA Suite, you need to accept the agreement for the Enterprise Edition database and SOA Suite. You don’t need the SOA Infrastructure; it is part of the SOA Suite image.


docker login -u OTNusername -p OTNpassword

Pull, tag, create env files

Pulling the images can take a while… (can be hours on Wifi). The commands for pulling differ slightly from the examples given in the image documentation in the Container Registry because image names have recently changed. For consistent access, tag them.


docker pull
docker tag oracle/database:

The database requires a configuration file. The settings in this file are not correctly applied by the installation which is executed when a container is created from the image however. I’ve updated the configuration file to reflect what is actually created:


SOA Suite

docker pull
docker tag oracle/soa:

The Admin Server also requires a configuration file:


As you can see, you can use the same database for multiple SOA schema’s since the RCU prefix is configurable.

The Managed Server also requires a configuration file:


Make sure the Managed Server mentioned in the Admin Server configuration file matches the Managed Server in the Managed Server configuration file. The Admin Server installation creates a for the Managed Server. If the server name does not match, the Managed Server will not boot.

Create local folders and network

Since you might not want to lose your domain or database files when you remove your container and start it again, you can create a location on your host machine where the domain will be created and the database can store its files. Make sure the user running the containers has userid/groupid 1000 for the below commands to allow the user access to the directories. Run the below commands as root. They differ slightly from the manual since errors will occur if SOAVolume/SOA does not exist.

mkdir -p /scratch/DockerVolume/SOAVolume/SOA
chown 1000:1000 /scratch/DockerVolume/SOAVolume/
chmod -R 700 /scratch/DockerVolume/SOAVolume/

Create a network for the database and SOA servers:

docker network create -d bridge SOANet


Start the database

You’ll first need the database. You can run it by:

#Start the database
docker run --name soadb --network=SOANet -p 1521:1521 -p 5500:5500 -v /scratch/DockerVolume/SOAVolume/DB:/opt/oracle/oradata --env-file /software/db.env.list oracle/database:

This installs and starts the database. db.env.list, which is described above, should be in /software in this case.

SOA Suite

In the examples documented, it is indicated you can run the Admin Server and the Managed Server in separate containers. You can and they will startup. However, the Admin Server cannot manage the Managed Server and the WebLogic Console / EM don’t show the Managed Server status. The configuration in the Docker container uses a single machine with a single host-name and indicates both the Managed Server and Admin Server both run there. In order to fix this, I’ll suggest two easy workarounds.

Port forwarding. Admin Server and Managed Server in separate containers

You can create a port-forward from the Admin Server to the Managed Server. This allows the WebLogic Console / EM and Admin Server to access the Managed Server at ‘localhost’ within the Docker container on port 8001.

#This command starts an interactive shell which runs the Admin Server. Wait until it is up before continuing!
docker run -i -t --name soaas --network=SOANet -p 7001:7001 -v /scratch/DockerVolume/SOAVolume/SOA:/u01/oracle/user_projects --env-file /software/adminserver.env.list oracle/soa:

#This command starts an interactive shell which runs the Managed Server.
docker run -i -t --name soams --network=SOANet -p 8001:8001 --volumes-from soaas --env-file /software/soaserver.env.list oracle/soa: "/u01/oracle/dockertools/"

#The below commands install and run socat to do the port mapping from Admin Server port 8001 to Managed Server port 8001
docker exec -u root soaas yum -y install socat
docker exec -d -u root soaas "/usr/bin/socat" TCP4-LISTEN:8001,fork TCP4:soams:8001"

The container is very limited. It does not contain executables for ping, netstat, wget, ifconfig, iptables and several other common tools. socat seemed an easy solution (easier than iptables or SSH tunnels) to do port forwarding and it worked nicely.

Admin Server and Managed Server in a single container

An alternative is to run the both the Managed Server and the Admin Server in the same container. Here you start the Admin Server with both the configuration files so all environment variables are available. Once the Admin Server is started, the Managed Server can be started in a separate shell with docker exec.

#Start Admin Server
docker run -i -t --name soaas --network=SOANet -p 7001:7001 -p 8001:8001 -v /scratch/DockerVolume/SOAVolume/SOA:/u01/oracle/user_projects --env-file /software/adminserver.env.list --env-file /software/soaserver.env.list oracle/soa:
#Start Managed Server
docker exec -it soaas "/u01/oracle/dockertools/"

Start the NodeManager

If you like (but you don’t have to), you can start the NodeManager in both set-ups like;

docker exec -d soaas "/u01/oracle/user_projects/domains/InfraDomain/bin/"

The NodeManager runs on port 5658.

How does it look?

A normal SOA Suite environment.

28 thoughts on “SOA Suite 12c in Docker containers. Only a couple of commands, no installers, no third party scripts

  1. Hi Maarten! Can we have dockerized SOA Suite in production? How does it impact licencing? Let say I have 8 containers for my SOA Suite cluster, how many licences do I need? How does it work for ephemeral containers though may not be a workable solution for SOA suite.

    1. I’m no expert on licensing but the following might help in order to get an indication: ‘Support Information for Oracle WebLogic Server Running in Docker Containers (Doc ID 2017945.1)’. This seems to indicate SOA Suite in Docker containers is currently supported in development, test and production environments for You can run SOA Suite in Kubernetes, however it is still in preview for early adopters. See here If you want to know more specifically how many licenses you would need, I think it is best to contact Oracle directly. Personally I think (this is an estimate, not based on actual experience at customers) that SOA Suite might be a bit heavy for running in containers and Kubernetes management of SOA Suite containers might be more challenging than beneficial. Just running in a Docker container (without Kubernetes) will provide you little benefit over running on bare metal.

  2. Hi Maarten, i am working in Oracle AIA team , container registry having soasuite , but we need Foundation Pack on top of it , to run the AIA composites , for that we are created SCEApp.jar file to deploy on soasuite , but i am dono how to deploy that jar file on top of soa suite , please suggest , tones of thanks to you .

  3. How can I open the db.env.list, adminserver.env.list and soaserver.env.list configuration files?

      1. My db.env.list:



        When I run this command “docker run -i -t –name soasuite –network=SOANet -p 7001:7001 –env-file c:\software\adminserver.env.list ora
        cle/soa:”, give me the following error:

        ERROR – RCU-6090 Connection step validation failed.
        CAUSE – RCU-6090 Skipping main operation: failed to connect to database because database details were missing or invalid.
        ACTION – RCU-6090 Provide correct database details and try again.

        Can you help me solve this error?

  4. Hi Maarten Smeets, I wish you were well.
    My name is John and I am trying to install oracle database and SOA in docker using this tutorial. The database is already there, but I can’t install SOA. Actually, I don’t know where to find the adminserver.env.list configuration file and soaserver.env.list. Could you help me with this?

  5. To be fair, this explanation does not cover a lot of problems that I encountered on the way of trying to install this. I give up because there were to many errors during installing and running the docker containers.

  6. Hi
    I can see that even if we define a custom ORACLE_SID in the db.env.list still the database will be created with the default ORCLCDB. Is like the docker run ignores the db.env.list details.
    On the other hand even if the default ORCLCDB SID details are used, from the SQLDeveloper I have an error pointing to wrong password so the db.env.list password is also not used when I create the container.
    So, as a summary: how can we make sure that the db.env.list is not ignored when we create the container ?

    Other than this db.env.list file issues, I can say that the article is very clear with all the steps needed: great article 😉

  7. Hi,
    I am getting the same error, any idea what is the fix for this below error???

    Problem invoking WLST – Traceback (innermost last):
    File “/u01/oracle/dockertools/”, line 482, in ?
    File “/u01/oracle/dockertools/”, line 96, in __init__
    File “/u01/oracle/dockertools/”, line 383, in validateDirectory
    File “/u01/oracle/wlserver/common/wlst/modules/jython-modules.jar/Lib/”, line 158, in makedirs
    OSError: [Errno 0] couldn’t make directories: /u01/oracle/user_projects/domains

  8. Maarteen,

    i am getting source path error in macos, i have added source path in preferences/file sharing. can you please suggest..

    docker run –name soadb –network=SOANet -p 1521:1521 -p 5500:5500 -v /scratch/DockerVolume/SOAVolume/DB:/opt/oracle/oradata –env-file db.env.list oracle/database:
    docker: Error response from daemon: error while creating mount source path ‘/scratch/DockerVolume/SOAVolume/DB’: mkdir /scratch/DockerVolume/SOAVolume/DB: permission denied.
    ERRO[0000] error waiting for container: context canceled

  9. Hi,
    I am getting the error as mkdir: cannot create directory ‘/u01/oracle/user_projects’ : Permission denied while creating the Admin server.

    Problem invoking WLST – Traceback (innermost last):
    File “/u01/oracle/dockertools/”, line 482, in ?
    File “/u01/oracle/dockertools/”, line 96, in __init__
    File “/u01/oracle/dockertools/”, line 383, in validateDirectory
    File “/u01/oracle/wlserver/common/wlst/modules/jython-modules.jar/Lib/”, line 158, in makedirs
    OSError: [Errno 0] couldn’t make directories: /u01/oracle/user_projects/domains


  10. Hey Maarten, does this image have the binaries for creating an OSB managed server as well?

    1. Yes it does. It has SOA, BPM and OSB. For more information see here:,AI_REPOSITORY,AI_REPOSITORY_NAME,P4_REPOSITORY_NAME,P4_EULA_ID,P4_BUSINESS_AREA_ID:252,252,Oracle%20SOA%20Suite,Oracle%20SOA%20Suite,1,0&cs=3QKjfGaVHRmPlj9-XDqgu05hZhLt9i1Wryni7lajaLgZo_n6K17Zs5QIb02z1o3PF6oIp-vbfXQRIO1FDPQURjQ (it’s a link to the soasuite Docker image in Oracle’s container registry)

  11. I tried the above steps which you mentioned, and I am getting the error as mkdir: cannot create directory ‘/u01/oracle/user_projects’ : Permission denied while creating the Admin server.

    Problem invoking WLST – Traceback (innermost last):
    File “/u01/oracle/dockertools/”, line 482, in ?
    File “/u01/oracle/dockertools/”, line 96, in __init__
    File “/u01/oracle/dockertools/”, line 383, in validateDirectory
    File “/u01/oracle/wlserver/common/wlst/modules/jython-modules.jar/Lib/”, line 158, in makedirs
    OSError: [Errno 0] couldn’t make directories: /u01/oracle/user_projects/domains

    1. You have to uninstall “docker-snap” and install “docker-ce” -> google -> install docker-ce -> done

  12. We are looking at having Oracle SOA Suite in a clustered fashion running on docker container in AWS.
    However when we see the below note:
    Support Information for Oracle WebLogic Server and Oracle Fusion Middleware Running in Docker Containers (Doc ID 2017945.1)
    It mentions it not meant/supported for production usage. Hence i do not think we can go with this configuration except for a developers laptop.

  13. Maarteen,

    Once I login and I do docker pull

    Login Succeeded
    webadmin:soasuite maxm$ docker pull
    Error response from daemon: pull access denied for, repository does not exist or may require ‘docker login’
    webadmin:soasuite maxm$ docker pull

  14. Hi Maarten, I tried the above steps which you mentioned, and I am getting the error as mkdir: cannot create directory ‘/u01/oracle/user_projects’ : Permission denied while creating the Admin server. I created the oracle user and created this folder manually and given all the permission but still getting the same error.

  15. Hi Maarten, what Linux distro did you run the above Docker? Was it Oracle Linux?

  16. great article 🙂 thanks for writing this. I might try this in sometime.

Comments are closed.

Next Post

Rapidly spinning up a VM with Ubuntu and Docker–on my Windows machine using Vagrant and VirtualBox

I have a Windows laptop. And of course I want to work with Docker containers. Using the Docker Quickstart Terminal is one way of doing so, and to some extent that works fine. But whenever I want to have more control over the Linux environment that runs the Docker host, […]
%d bloggers like this: