2 Building WebLogic Server Images on Docker

This section discusses how to use the Dockerfiles and supporting scripts that Oracle has made available on GitHub to build your own WebLogic Server 12.2.1 Docker images.

Topics include:

Building WebLogic Server Images on Docker

To build the Oracle WebLogic install image, you must first have the Oracle Linux and Oracle JDK images already running. Pull the Oracle Linux 6 or 7 image from Docker Hub. To create the Oracle JDK image, download the Dockerfile from GitHub/Oracle JDK; this Docker file extends the Oracle Linux image and installs the JDK. Download the JDK into the /OracleJDK/java-x directory.

$ sudo docker build –t oracle/jdk:8

Before you begin, choose the installation type you want to use, either the Generic or Developer installer, as described in About WebLogic Server Images on Docker. Then follow these steps:

Download the required WebLogic Server installer in the dockerfiles/12.2.1 directory.
Change to the /dockerfiles directory and run the buildDockerImage.sh script as root:
```
$ sudo sh buildDockerImage.sh -h
```
Usage: buildDockerImage.sh [-d|-g] [-v] 12.2.1

where d: creates image based on the developer distribution.

where g: creates image based on the generic distribution.

where v: specifies the WebLogic version.

Note:

The resulting image will not have a domain preconfigured. Oracle provides a separate Dockerfile and supporting scripts to extend the WebLogic Server install image and create a WebLogic Server domain image.

Samples for WebLogic Server Domain Creation

To give you an idea on how to create a domain from a custom Dockerfile to extend the WebLogic Server install image, Oracle provides some samples for WebLogic Server 12c (12.2.1) for both the Developer and Generic distributions. The samples are in the samples/1221-domain directory.

Sample Domain for WebLogic Server 12c (12.2.1)

This Dockerfile will create an image by extending oracle/weblogic:12.2.1-dev (from the Developer distribution). It will configure a base_domain with the following settings:

Domain Name: base_domain
Admin Port:8001
Administrator Username: weblogic
Administrator Password: welcome1
Oracle Linux Username: oracle
Oracle Linux Password: welcome1
Cluster Name: DockerCluster
Managed Server Port: 7001
NodeManager Port : 5556
JVM Memory Settings: -Xms236m –Xmx512m –XXLMacPermSize=2048m

Write Your Own Oracle WebLogic Server Domain with WLST

The best way to create your own domain, or to extend domains, is by using WLST. The WLST script used to create domains in the Dockerfile container is create-wls-domain.py. This script by default adds JMS resources and a few other settings.

You may want to tune this script with your own setup to create data sources and connection pools, security realms, deploy artifacts, and so on. You can also extend images and override the existing domain, or create a new one with WLST.

For more information about using WLST, refer to Understanding the WebLogic Scripting Tool.

Building a Sample Docker Image of a WebLogic Server Domain

To build a sample of a WebLogic Server image with a domain configured, follow these steps:

Make sure you have oracle/weblogic:12.2.1-dev image built as described in Building WebLogic Server Images on Docker. If not, change to the /dockerfiles directory and run the buildDockerImage.sh script as root:
```
$ sudo sh buildDockerImage.sh -v 12.2.1 [-d|-g]
```

Change to the /samples/1221-domain directory and run the docker build command:

$ sudo docker build -t samplewls:12.2.1 –build-arg ADMIN_PASSWORD=welcome1

Verify that you have the image in place by running the docker images command:
```
$ sudo docker images
```

Running an Administration Server Container

When you use the WebLogic Server domain image to start your container, an Administration Server starts running in the container by default. The default Administration Server name is AdminServer; the default port configuration is 8001; and the default Administration Server container name is wlsadmin. When running more than one domain in the same single host, you must change the Administration Server name, port number, and container name.

To start the Administration Server:

Execute the docker run command:
```
$ sudo docker run -d --name=wlsadmin samplewls:12.2.1
```
where samplewls:12.2.1 is the WebLogic Server domain image tag. The samples Dockerfiles define startWebLogic.sh as the default CMD (command).
To obtain the IP address of the Administration Server Container run the docker inspect command:
```
$ sudo docker inspect --format '{{ .NetworkSettings.IPAddress }}' wlsadmin
```
Open the Administration Server's web-based console at http:// xxx.xx.x.xx:8001/console.

Note:

If you have multiple WebLogic Server domains running on the same host (such as multiple Administration Servers), change the -name parameter (name of the Administration Server container) and the -p parameter (port of the Administration Server).

Running a Managed Server Container

Managed Server containers have a Node Manager and a Managed Server running in it. These Managed Server containers communicate to an Administration Server container by linking (-link command) using the Administration Server container name. The Administration Server container name defaults to wlsadmin.

When there are more than one domain running on the same host, then the Administration Server container name needs to be unique; you need to change the Administration Server container name by using the -name parameter and matching the name given in the -link command of each Managed Server container.

There are three different ways to start a Managed Server container:

Start Node Manager (manually):

$ sudo docker run -d -link wlsadmin:wlsadmin <image-name> startNodeManager.sh

Start Node Manager and create a Machine automatically:

$ sudo docker run -d -link wlsadmin:wlsadmin <image-name>  createMachine.sh

Start Node Manager, create a Machine, and create a Managed Server automatically:
```
$ sudo docker run -d -link wlsadmin:wlsadmin <image-name>  createServer.sh
```

Sample Managed Server Command and Parameters

A sample docker run command for a Managed Server container and a listing of available parameters is as follows:

$ sudo docker run -d -link wlsadmin:wlsadmin \
     -p <NM Port>:5556 -p <MS Port>:<MS Port> \
     -name=<Container name> \
     -e MS_HOST=<Host address where Managed Server container runs> \
     -e MS_PORT=<Managed Server port> \
     -e NM_HOST=<Host address where Managed Server container runs> \
     -e NM_PORT=<Node Manager Port (should match the port in the -p)> \
     <image name> \
     <createMachine.sh, startNodeManager.sh, createServer.sh>

Script Variables

The supported scripts have a list of variables that must be properly configured, as defined in Table 2-1.

Table 2-1 Script Variables and Definitions

Variable	Definition
`ADMIN_USERNAME`	Username of the AdminServer `weblogic` user. Default: `weblogic`
`ADMIN_PASSWORD`	Password of `ADMIN_USERNAME`. Defaults to value passed during Dockerfile build. (`welcome1` in the samples)
`ADMIN_URL`	t3 URL of the AdminServer. Default: `t3://wlsadmin:8001`
`CONTAINER_NAME`	Name of the Machine to be created. Default: `node manager_ + hash` of the container
`NM_HOST`	IP address where Node Manager can be reached. Default: IP address of the container
`NM_PORT`	Port of Node Manager. Default: `5556`
`MS_HOST`	IP address where Managed Server can be reached. Default: IP address of the container
`MS_PORT`	Port of Managed Server. Default: `7001`

Examples of Using the Script Variables

If you want to run a "Single-Host" configuration on a remote server, you must expose ports and addresses of the Admin server, Managed Servers and Node Manager as shown in the following examples:

$ sudo docker run -d -link wlsadmin:wlsadmin -p 5556:5556 -name="wlsnm0" -e NM_HOST="xx.xxx.xx.xxx" -e NM_PORT="5556" samplewls:12.2.1 createMachine.sh

$ sudo docker run -d -link wlsadmin:wlsadmin   -p 7003:7003
-e MS_HOST=xx.xxx.xx.xxx -e MS_PORT=7003 samplewls:12.2.1 createServer.sh

$ sudo docker run -d -link wlsadmin:wlsadmin   -p 7002:7002
-e MS_HOST= xx.xxx.xx.xxx  -e MS_PORT=7002 samplewls:12.2.1 createServer.sh

Note:

You must assign a new, unique listen port when you create an additional Managed Server container on a host OS where a Managed Server container is already running. This prevents multiple Managed Servers running on the same host OS from listening on the same listen port.

If you used the createServer.sh command:

Access the Administration Server console at http://admin-container-ip:8001 /console.
In the Domain Structure tree, expand Environment.
Select Machines to open the Summary of Machines page and verify that you have a Machine registered.
Click your registered Machine in the table, and then use the Node Manager and Servers tabs to verify that your Node Manager and Managed Server are also configured.
Open the Servers page, select the Control tab, and start your server.

Communicating With Servers on a Remote Host

Another possible topology is to run a single Admin Server container communicating with Oracle WebLogic Server running on a remote host. Use -add-host so that the container assumes the IP address of the host where it is running instead of the local container IP address:

$ sudo docker run -d -p 8001:8001 -net=host -add-host=hostname: <host ip address where container is running> -name wlsadmin samplewls:12.2.1

For this topology to work, the following configurations are necessary:

The listen address of the AdminServer in the Docker container has to be configured.
The listen address of the AdminServer in the remote host has to be configured.
The client must use the hosts IP addresses to get the initial context for JNDI lookup.

Creating a WebLogic MedRec Sample Domain

The Supplemental Quick Installer is a lightweight installer that contains all the necessary artifacts to develop and test applications on Oracle WebLogic Server 12.2.1. You can extend the WebLogic developer install image (oracle/weblogic:12.2.1-dev) to create a WebLogic Server domain image with the MedRec application deployed. The Supplemental Quick Installer is located at /samples/1221-medrec.

To create the MedRec sample domain:

Make sure you have the oracle/weblogic:12.2.1-dev image built. If not go into dockerfiles and call:
```
$ sudo sh buildDockerImage.sh -v 12.2.1 –d
```
Changed directories to /samples/1221-domain and run the following command:
```
$ sudo docker build -t samplewls:12.2.1
```
Build the medrec image:
```
$ sudo docker build -t 1221-medrec
```

Run a container from this new sample domain image:

$ sudo docker run –d –p 7011:7011 1221-medrec

Access the AdminServer Console at http://localhost:7011/medrec.

Running an Oracle WebLogic Server Domain in a Multi Host Environment

Docker 1.9 introduced the ability to network containers together running on multi-host operating systems or virtual machines. Oracle WebLogic Server 12c domains are certified on servers running in Docker containers that were distributed in different physical hosts or virtual machines. In this Docker environment, the WebLogic servers running in the cluster have all the high availability properties of a WebLogic Server cluster (for example Session Replication and Singleton Service Migration).

Docker has developed tools that make it significantly easier to create such multi-host environments and network them together:

Docker Machine: Docker Machine is a tool that lets you install Docker Engine on virtual hosts and manage the hosts with docker-machine commands.
Docker Swarm: Docker Swarm is native clustering for Docker. It turns a pool of Docker hosts into a single, virtual Docker host. Because Docker Swarm serves the standard Docker API, any tool that already communicates with a Docker daemon can use Swarm to transparently scale to multiple hosts.
Docker Overlay Network: Dockers Overlay network driver supports multi-host networking natively out-of-the-box while still providing better container isolation.
Docker Compose: Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a Compose file to configure your application services. Then, using a single command, you create and start all the services from your configuration.
Docker Registry: The Registry is a stateless, highly scalable server side application that stores and lets you distribute Docker images.
Consul: Consul makes it simple for services to register themselves and to discover other services via a DNS or HTTP interface.

Note:

To run Docker 1.10 or higher, you need UEK4

Building Application Images

In a WebLogic Server domain running in a Docker environment, you deploy applications by extending the WebLogic Server Domain image to create an Application image. Samples are provided on GitHub at /samples/1221-appdeploy. The WLST script used to deploy the sample application and create the 1221-appdeploy image is /samples/1221-appdeploy/container-scripts/app-deploy.py. This script by default deploys the sample application to all servers in the domain. You can deploy your own applications by modifying the WLST scripts or create a new one with WLST.

To build an application image:

$ cd ~/docker-images/OracleWebLogic/samples/1221-appdeploy
$ sudo docker build -t 1221-appdeploy

Apache Plugin Web Tier Images

The Apache Plugin provides the ability to load balance traffic to WebLogic Managed servers in a WebLogic cluster. Each Managed server is running in its own Docker container and the Apache Plugin Web tier is also running inside of its own Docker container. In a multi-host environment, the traffic can be routed to any Managed Server container running in the Docker Swarm cluster and networked together by the Docker Overlay Network.

A sample of how to create the Apache Plugin Web tier images from a custom Dockerfile is provided at /samples/1221-webtier-apache. The best way to create your own image is to edit the Dockerfile and the weblogic.conf file to fit your environment.

The Dockerfile extends the httpd:2.4 image and installs the Apache Plugin. To build the WebLogic Web tier image:

$ cd ~/docker-images/OracleWebLogic/samples/1221-webtier-apache
$ sudo docker build -t webtier

Building WebLogic Distributed Domains and Clusters

The following images are required to create Oracle WebLogic distributed domains and clusters across multiple hosts or virtual machines:

Oracle Linux
Oracle JDK Image
WebLogic Install Image
WebLogic Domain Image
WebLogic Application Image
Web tier Image

To distributed WebLogic domains and clusters you must install the Docker Engine in every host where you plan on running containers. Run the images and start the containers from those images. The only requirement for these containers to network together is the Docker Overlay network. The overlay network requires a valid key-value store service. Currently, Docker supports Consul, Etcd, and ZooKeeper (Distributed store), Refer to Docker networking for the steps to enable it.

Alternatively, you can use the Docker tools previously described to create WebLogic distributed domains and clusters. The Docker Machine starts a Virtual Box with the Docker Engine running inside. You can have as many Docker Machines in your environment as you want. To start a machine:

$ docker-machine create

Every Docker Machine participates in a Docker Swarm cluster and are networked using the Docker Overlay network. The Docker Registry allows you to push images into the registry and then run containers from these images from outside the VM using scripts. Every virtual machine that is part of the Docker Swarm is networked together with the Docker Overlay network. Every container running in the VM can communicate with any other container running in a different VM in the Docker Swarm. This allows you to run the WebLogic servers in many different VMs and distribute the WebLogic Server domain or cluster across several VMs. To look at the Docker networks, run the following commands:

$ sudo docker network ls
$ sudo docker network inspect <overlay network name>

Scripts to create a WebLogic Server Domain in a multi-host environment using the tools previously described are available at /samples/1221-multihost. The bootstrap.sh script starts two Docker Machines: the weblogic-orchestrator and the weblogic-master. The weblogic-orchestrator has the Docker Registry that registers the images that are required to run the containers and has Consul to help start services. The weblogic-master has the Docker Swarm, the Overlay Network, and the WebLogic Admin Server container running in the VM. After starting the two Docker machines, the appdeploy image is pushed into the registry running in the weblogic-orchestrator machine. Lastly, the bootstrap script calls the post-bootstrap script; this script runs an Admin server Docker Container in the weblogic-master machine from the app-deploy image that has been pushed to the registry.

To start a new Docker machine where the Managed Server runs, call /samples/1221-multihost/create-machine.sh. The new Docker Machine is part of the Docker Swarm and the Managed Server containers running in this VM can network using the Overlay network with other containers in the Swarm. After running the create-machine.sh script, you can see the Docker Machines running in your environment by invoking the following command:

$ sudo docker-machine ls

To start Managed Server containers from the app-deploy image, call /samples/1221-multihost/create-container.sh. If you want the Managed server container to be started in a particular Docker machine, provide the machine name as a parameter (./create-container.sh <machine name>); otherwise, the container can start in any of the Docker Machines in the Swarm.

To load balance requests to the Managed Servers in the Oracle WebLogic Cluster, create a Docker container running the Apache Plugin Web tier. This container runs in one of the Docker Machines in the Docker Swarm and is networked to all other containers in the Swarm. The /samples/1221-multihost/start-webtier.sh script discovers all Managed Servers running in the Swarm; creates the string WEBLOGIC_CLUSTER; pushes the webtier image to the registry; and starts a webtier container on the weblogic-master machine. The WEBLOGIC_CLUSTER string is set as an environment parameter when starting the Apache Web tier container and is set in the weblogic.conf file. Also, note that the Apache Web tier container is bound to port 80 of the weblogic-master machine.

Call the sample application using the Apache Web tier. In your browser, use the IP address of the weblogic-master machine and port 80:

http://xxx.xxx.xxx:80/sample

To obtain the IP address of the weblogic-master machine, run the command:

$ sudo docker-machine ls

You can repeat the steps above to create additional Docker Machines and Managed Servers running in the machines.

Additional Considerations When Running WebLogic Server Images in Docker Containers

This section addresses some additional considerations when running WebLogic Server images in Docker containers.

How the File System Is Managed in Containers

WebLogic Server configuration files, server logs, file stores, and so on, are all kept in the container file system. When a Docker container is destroyed you will lose your entire file system. There are two alternatives that you can use to avoid losing your file system, described below and illustrated in Figure 2-1:

Maintain a "data-only" container to store your domain file system. (Container1 and DataCont-1 in the figure.)
Use the host file system to store the container's local file system (Container2 in the figure.)

Note:

Container0 in the figure represents a single WebLogic Server that is stateless. Its only function is to deploy applications and resources and does not need to maintain its file system. If it is destroyed, you can just start a new one from the image.

To minimize the dependency on the file system, Oracle recommends:

Keeping your stores, such as TLog and JMS stores, in the database.
If you use XA Transactions, use XATransactions without TLog write, because this minimizes the writing to the TLog. See "XA Transactions without Transaction TLog Write" in Developing JTA Applications for Oracle WebLogic Server.

Figure 2-1 Managing the File System with Docker Containers

Description of "Figure 2-1 Managing the File System with Docker Containers"

Patching and Upgrading WebLogic Server Images

To patch or upgrade your WebLogic Server images created with the WebLogic Server generic installation image, follow these steps:

Upgrade or patch the image by extending the WebLogic Server install Docker image.
Use the Docker cp (copy) command to copy your domain directory to a destination directory on either the host or a "data-only" container.
Remove the container.
Run the new container from the extended image (with upgrade/patch).
Use the Docker cp command to copy your domain directory back to the upgraded container.

Security Concerns Regarding Docker and Linux Containers

The following security concerns have been raised regarding Docker and Linux containers:

One area of concern is whether it is possible to isolate code running in separate containers from each other. There are no known issues impacting the ability to run WebLogic Server in such an environment at this time.
Another security concern is the source of the Docker images. You should only obtain Docker images from trusted sources and you need to be aware of the frequency of updates and the nature of the controls on Docker Hub.
You should stay current with Docker and Linux technology and remain aware of security issues that are raised in each.
Docker containers default network mode of "Bridge Networking" does not support multicast. Docker containers "Host Networking" supports multicast, but provides less isolation since it uses the host networking stack. Oracle recommends the use of unicast as the WebLogic Server clustering protocol when running in Docker containers.