Oracle has added Oracle REST Data Services (ORDS) to the Docker build files family on GitHub, which means that you can now easily dockerize ORDS. If you don’t know yet what ORDS is, it’s a free technology from Oracle that allows you to REST-enable your Oracle databases. More specifically, with ORDS you can just fire off regular REST calls to modify or retrieve data from one or many Oracle databases without having to know how to write SQL; not that knowing SQL is a bad thing! 🙂 In modern application and microservices architectures REST has become more and more popular for exchanging information. ORDS enables you to easily exchange data from and to Oracle databases via REST without having to write lines and lines of code yourself. For more information on what ORDS is and what it can do, check out Jeff Smith’s blog post about ORDS.
What you need
- The ORDS install zip file, you can download it from the Oracle Technology Network
- An Java Server JRE 8 Docker base image
- An Oracle Database running somewhere that ORDS should expose via REST
Environment
My environment as of writing this blog is as follows:
- Oracle Linux 7.4 (4.1.12-112.14.15.el7uek.x86_64)
- Docker 17.06.2-ol (docker-engine.x86_64 17.06.2.ol-1.0.1.el7)
- Java Server JRE 1.8.0_172
- Oracle REST Data Services 18.1.1
Building the Oracle REST Data Services Docker image
Obtaining the required files
As with all the GitHub build files from Oracle you first have to download them. There are various ways of how you can download them. For example, you can just clone the Git repository directly. Or you can just download a zip file from GitHub containing all the required files. This option is best for people who don’t know Git. The URL to the zip file is https://github.com/oracle/docker-images/archive/master.zip, which you can download via wget or with your browser and then unzip:
$ wget https://github.com/oracle/docker-images/archive/master.zip --2018-05-04 14:20:26-- https://github.com/oracle/docker-images/archive/master.zip Resolving github.com (github.com)... 192.30.255.113, 192.30.255.112 Connecting to github.com (github.com)|192.30.255.113|:443... connected. HTTP request sent, awaiting response... 302 Found Location: https://codeload.github.com/oracle/docker-images/zip/master [following] --2018-05-04 14:20:26-- https://codeload.github.com/oracle/docker-images/zip/master Connecting to codeload.github.com (codeload.github.com)|192.30.255.120|:443... connected. Proxy request sent, awaiting response... 200 OK Length: unspecified [application/zip] Saving to: ‘master.zip’ [ <=> ] 7,601,317 5.37MB/s in 1.3s 2018-05-04 14:20:28 (5.37 MB/s) - ‘master.zip’ saved [7601317] $ unzip master.zip Archive: master.zip 184cded65f147766c41b2179ee31ba5551185507 creating: docker-images-master/ extracting: docker-images-master/.gitattributes inflating: docker-images-master/.gitignore extracting: docker-images-master/.gitmodules inflating: docker-images-master/CODEOWNERS inflating: docker-images-master/CONTRIBUTING.md ... ... ... creating: docker-images-master/OracleRestDataServices/ extracting: docker-images-master/OracleRestDataServices/.gitignore inflating: docker-images-master/OracleRestDataServices/COPYRIGHT inflating: docker-images-master/OracleRestDataServices/LICENSE inflating: docker-images-master/OracleRestDataServices/README.md creating: docker-images-master/OracleRestDataServices/dockerfiles/ ... ... ... inflating: docker-images-master/README.md $
Next you will have to download the ORDS Installer zip file. As said above, you can get it from the Oracle Technology Network:
$ ls -al ords.18*.zip -rw-r--r--. 1 oracle oracle 61118609 May 4 14:38 ords.18.1.1.95.1251.zip
Building the Java Server JRE base image
The ORDS Docker image is built on the oracle/serverjre:8 base image. That image is not on the Docker Hub so Docker cannot just pull the image automatically. Instead you first have to build that image before you can proceed to building the ORDS image. Building the Java Server JRE image is straight forward. First you need to download the latest server-jre-8*linux-x64.tar.gz file from the Oracle Technology Network:
$ ls -al server-jre*.tar.gz -rw-r--r--. 1 oracle oracle 54817401 May 4 14:30 server-jre-8u172-linux-x64.tar.gz
Once you have the file, copy it into the OracleJava/java-8 folder and run the Java Server JRE Docker build.sh script:
$ cd docker-images-master/OracleJava/java-8 $ cp ~/server-jre-8u172-linux-x64.tar.gz . $ ./build.sh Sending build context to Docker daemon 54.82MB Step 1/5 : FROM oraclelinux:7-slim ---> 9870bebfb1d5 Step 2/5 : MAINTAINER Bruno Borges <bruno.borges@oracle.com> ---> Running in b1847c1a647e ---> 3bc9baedf526 Removing intermediate container b1847c1a647e Step 3/5 : ENV JAVA_PKG server-jre-8u*-linux-x64.tar.gz JAVA_HOME /usr/java/default ---> Running in 50998175529b ---> 017598682688 Removing intermediate container 50998175529b Step 4/5 : ADD $JAVA_PKG /usr/java/ ---> 6704a281de8b Removing intermediate container b6b6a08d3c38 Step 5/5 : RUN export JAVA_DIR=$(ls -1 -d /usr/java/*) && ln -s $JAVA_DIR /usr/java/latest && ln -s $JAVA_DIR /usr/java/default && alternatives --install /usr/bin/java java $JAVA_DIR/bin/java 20000 && alternatives --install /usr/bin/javac javac $JAVA_DIR/bin/javac 20000 && alternatives --install /usr/bin/jar jar $JAVA_DIR/bin/jar 20000 ---> Running in 281fe2343d2c ---> f65b2559f3a5 Removing intermediate container 281fe2343d2c Successfully built f65b2559f3a5 Successfully tagged oracle/serverjre:8 $
That’s it! Now you have a brand new oracle/serverjre:8 Docker image:
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE oracle/serverjre 8 f65b2559f3a5 45 seconds ago 269MB oracle/database 12.2.0.1-se2 323887b92e8f 3 weeks ago 6.38GB oracle/database 12.2.0.1-ee 08d230aa1d55 3 weeks ago 6.39GB oracle/database 12.1.0.2-se2 b4999e09453e 3 weeks ago 5.08GB oracle/database 12.1.0.2-ee aee62bc26119 3 weeks ago 5.18GB oracle/database 11.2.0.2-xe 50712d409891 3 weeks ago 809MB oraclelinux 7-slim 9870bebfb1d5 5 months ago 118MB $
Building the ORDS Docker image
Once you have the oracle/serverjre:8 Docker image on your machine you can now go ahead and build the actual ORDS Docker image. This is also a rather easy task, just put the installer zip file into the OracleRestDataServices/dockerfiles/ folder and run the buildDockerImage.sh script:
$ cd ../../OracleRestDataServices/dockerfiles/ $ mv ~/ords.18.1.1.95.1251.zip . $ ./buildDockerImage.sh Checking if required packages are present and valid... ords.18.1.1.95.1251.zip: OK ========================== DOCKER info: Containers: 2 Running: 0 Paused: 0 Stopped: 2 Images: 10 Server Version: 17.06.2-ol Storage Driver: btrfs Build Version: Btrfs v4.9.1 Library Version: 102 Logging Driver: json-file Cgroup Driver: cgroupfs Plugins: Volume: local Network: bridge host ipvlan macvlan null overlay Log: awslogs fluentd gcplogs gelf journald json-file logentries splunk syslog Swarm: inactive Runtimes: runc Default Runtime: runc Init Binary: docker-init containerd version: 6e23458c129b551d5c9871e5174f6b1b7f6d1170 runc version: 810190ceaa507aa2727d7ae6f4790c76ec150bd2 init version: 949e6fa Security Options: seccomp Profile: default selinux Kernel Version: 4.1.12-112.14.15.el7uek.x86_64 Operating System: Oracle Linux Server 7.4 OSType: linux Architecture: x86_64 CPUs: 2 Total Memory: 7.795GiB Name: localhost.localdomain ID: GZ5A:XQWB:F5TE:56JE:GR3J:VCXJ:I7BO:EGMY:K52K:JAS3:A7ZC:BOHQ Docker Root Dir: /var/lib/docker Debug Mode (client): false Debug Mode (server): false Registry: https://index.docker.io/v1/ Experimental: true Insecure Registries: 127.0.0.0/8 Live Restore Enabled: false ========================== Proxy settings were found and will be used during build. Building image 'oracle/restdataservices:18.1.1' ... Sending build context to Docker daemon 61.14MB Step 1/10 : FROM oracle/serverjre:8 ---> f65b2559f3a5 Step 2/10 : LABEL maintainer "gerald.venzl@oracle.com" ---> Running in d90ea0da50ae ---> 8959f49c8b7b Removing intermediate container d90ea0da50ae Step 3/10 : ENV ORDS_HOME /opt/oracle/ords INSTALL_FILE ords*.zip CONFIG_PROPS "ords_params.properties.tmpl" STANDALONE_PROPS "standalone.properties.tmpl" RUN_FILE "runOrds.sh" ---> Running in 84ae509c3b08 ---> 595f8228d224 Removing intermediate container 84ae509c3b08 Step 4/10 : COPY $INSTALL_FILE $CONFIG_PROPS $STANDALONE_PROPS $RUN_FILE $ORDS_HOME/ ---> 992d15c48302 Removing intermediate container 3088dd27464e Step 5/10 : RUN mkdir -p $ORDS_HOME/doc_root && chmod ug+x $ORDS_HOME/*.sh && groupadd dba && useradd -d /home/oracle -g dba -m -s /bin/bash oracle && cd $ORDS_HOME && jar -xf $INSTALL_FILE && rm $INSTALL_FILE && mkdir -p $ORDS_HOME/config/ords && java -jar $ORDS_HOME/ords.war configdir $ORDS_HOME/config && chown -R oracle:dba $ORDS_HOME ---> Running in a84bc25b8eb3 May 04, 2018 6:42:22 PM INFO: Set config.dir to /opt/oracle/ords/config in: /opt/oracle/ords/ords.war ---> 6ccfc92744ed Removing intermediate container a84bc25b8eb3 Step 6/10 : USER oracle ---> Running in c41c77b49add ---> 2bd11f2f8008 Removing intermediate container c41c77b49add Step 7/10 : WORKDIR /home/oracle ---> bc31d79cfb4a Removing intermediate container efef9dccf774 Step 8/10 : VOLUME $ORDS_HOME/config/ords ---> Running in dfbc7ee6f967 ---> 0ee4e7ed71b1 Removing intermediate container dfbc7ee6f967 Step 9/10 : EXPOSE 8888 ---> Running in deaebbf2950b ---> 25d777caccca Removing intermediate container deaebbf2950b Step 10/10 : CMD $ORDS_HOME/$RUN_FILE ---> Running in 0c2270a7fac4 ---> 4ee1ac73e1f9 Removing intermediate container 0c2270a7fac4 Successfully built 4ee1ac73e1f9 Successfully tagged oracle/restdataservices:18.1.1 Oracle Rest Data Services version 18.1.1 is ready to be extended: --> oracle/restdataservices:18.1.1 Build completed in 19 seconds. $
And now you have a brand new ORDS Docker image, in my case containing ORDS 18.1.1:
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE oracle/restdataservices 18.1.1 4ee1ac73e1f9 52 seconds ago 395MB oracle/serverjre 8 f65b2559f3a5 10 minutes ago 269MB oracle/database 12.2.0.1-se2 323887b92e8f 3 weeks ago 6.38GB oracle/database 12.2.0.1-ee 08d230aa1d55 3 weeks ago 6.39GB oracle/database 12.1.0.2-se2 b4999e09453e 3 weeks ago 5.08GB oracle/database 12.1.0.2-ee aee62bc26119 3 weeks ago 5.18GB oracle/database 11.2.0.2-xe 50712d409891 3 weeks ago 809MB oraclelinux 7-slim 9870bebfb1d5 5 months ago 118MB
There is one last thing to add here: By default the buildDockerImage.sh script runs a md5sum checksum on the ORDS zip file just to make sure that the file is intact. You see this as the very first output of the build script. You can skip that checksum by passing on the -i option. In general there is no need to skip the checksum step, however, ORDS releases on a quarterly basis and it may be the case that the GitHub repo hasn’t been updated with the latest checksum files yet. In such case you can still build your latest and greatest ORDS Docker image by bypassing the checksum via -i.
Running ORDS inside a Docker container
Now that you have an ORDS Docker image it’s time to run an actual container of it. As ORDS is a REST server in front of an Oracle Database you will need an Oracle Database that ORDS can REST-enable for you. I already do have my Oracle Database Docker images on the same machine and so I will go ahead and REST-enable a database within a Docker container. However, I should point out that having an Oracle Database inside a Docker container is no requirement for running ORDS inside Docker! In fact, you can quite happily manage many Oracle databases with ORDS, regardless where your Oracle databases are running, Docker, locally, on a server, in the cloud, etc.
Setting up the Docker network
If your Oracle Database is not running inside a Docker container, you can skip this step!
Because the database and ORDS are both running within Docker I first have to setup a Docker network that these two containers can use to communicate with each other. Creating the network is easily done with just a simple command docker network create:
$ docker network create ords-database-network b96c9fd9062f3aa0fb37db3dcd6319c6e3daefb99f52b82819e06f84b3ad38a0 $ docker network ls NETWORK ID NAME DRIVER SCOPE 0cad4fa350c8 bridge bridge local 0e6f604bfce9 host host local 26709c337f2f none null local b96c9fd9062f ords-database-network bridge local $
Running an Oracle Database Docker container
If your Oracle Database is not running inside a Docker container, you can skip this step!
See Creating an Oracle Database Docker image for how to run Oracle Database in Docker.
Once you have the network defined you can now start a new Oracle Database container. The --network option in the docker run command will allow you to attach your database container to the Docker network:
$ docker run -d --name ords-db --network=ords-database-network -v /home/oracle/oradata:/opt/oracle/oradata oracle/database:12.2.0.1-ee 074e2e85ccdaf00d4ae5d93f56a2532154070a8f95083a343e78a753d748505b $
Running an Oracle REST Data Services Docker container
To run an ORDS Docker container you will have to know the following details:
ORACLE_HOST: Host on which the Oracle Database is running (default: localhost)ORACLE_PORT: Port on which the Oracle Database is running (default: 1521)ORACLE_SERVICE: Oracle Database service name that ORDS should connect to (default: ORCLPDB1)ORACLE_PWD: SYS password of the Oracle DatabaseORDS_PWD: ORDS user password you want to use- A volume where to store the ORDS configuration files in
Once you have all of these you can go ahead and run your ORDS Docker container via the docker run command.
Note: Because my database is also running inside Docker, I will have to specify the --network parameter in order to allow the two containers to communicate. The hostname for my database host inside the Docker network is the same as my Database Docker container name. I will therefore use -e ORACLE_HOST=ords-db.
If you do not have the Oracle Database running in Docker, you can skip the --network parameter!
$ docker run --name ords \
> -p 8888:8888 \
> --network=ords-database-network \
> -e ORACLE_HOST=ords-db \
> -e ORACLE_PORT=1521 \
> -e ORACLE_SERVICE=ORCLPDB1 \
> -e ORACLE_PWD=LetsDocker \
> -e ORDS_PWD=LetsORDS \
> -v /home/oracle/ords:/opt/oracle/ords/config/ords:rw \
> oracle/restdataservices:18.1.1
May 07, 2018 3:47:43 AM
INFO: Updated configurations: defaults, apex_pu
May 07, 2018 3:47:43 AM oracle.dbtools.installer.InstallerBase log
INFO: Installing Oracle REST Data Services version 18.1.1.95.1251
May 07, 2018 3:47:43 AM oracle.dbtools.installer.Runner log
INFO: ... Log file written to /opt/oracle/ords/logs/ords_install_core_2018-05-07_034743_00762.log
May 07, 2018 3:47:44 AM oracle.dbtools.installer.Runner log
INFO: ... Verified database prerequisites
May 07, 2018 3:47:45 AM oracle.dbtools.installer.Runner log
INFO: ... Created Oracle REST Data Services schema
May 07, 2018 3:47:45 AM oracle.dbtools.installer.Runner log
INFO: ... Created Oracle REST Data Services proxy user
May 07, 2018 3:47:45 AM oracle.dbtools.installer.Runner log
INFO: ... Granted privileges to Oracle REST Data Services
May 07, 2018 3:47:48 AM oracle.dbtools.installer.Runner log
INFO: ... Created Oracle REST Data Services database objects
May 07, 2018 3:47:56 AM oracle.dbtools.installer.Runner log
INFO: ... Log file written to /opt/oracle/ords/logs/ords_install_datamodel_2018-05-07_034756_00488.log
May 07, 2018 3:47:57 AM oracle.dbtools.installer.Runner log
INFO: ... Log file written to /opt/oracle/ords/logs/ords_install_apex_2018-05-07_034757_00832.log
May 07, 2018 3:47:59 AM oracle.dbtools.installer.InstallerBase log
INFO: Completed installation for Oracle REST Data Services version 18.1.1.95.1251. Elapsed time: 00:00:15.397
2018-05-07 03:48:00.688:INFO::main: Logging initialized @1507ms to org.eclipse.jetty.util.log.StdErrLog
May 07, 2018 3:48:00 AM
INFO: HTTP and HTTP/2 cleartext listening on port: 8888
May 07, 2018 3:48:00 AM
INFO: The document root is serving static resources located in: /opt/oracle/ords/doc_root
2018-05-07 03:48:01.505:INFO:oejs.Server:main: jetty-9.4.z-SNAPSHOT, build timestamp: 2017-11-21T21:27:37Z, git hash: 82b8fb23f757335bb3329d540ce37a2a2615f0a8
2018-05-07 03:48:01.524:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
2018-05-07 03:48:01.525:INFO:oejs.session:main: No SessionScavenger set, using defaults
2018-05-07 03:48:01.526:INFO:oejs.session:main: Scavenging every 600000ms
May 07, 2018 3:48:02 AM
INFO: Creating Pool:|apex|pu|
May 07, 2018 3:48:02 AM
INFO: Configuration properties for: |apex|pu|
cache.caching=false
cache.directory=/tmp/apex/cache
cache.duration=days
cache.expiration=7
cache.maxEntries=500
cache.monitorInterval=60
cache.procedureNameList=
cache.type=lru
db.hostname=ords-db
db.password=******
db.port=1521
db.servicename=ORCLPDB1
db.username=ORDS_PUBLIC_USER
debug.debugger=false
debug.printDebugToScreen=false
error.keepErrorMessages=true
error.maxEntries=50
jdbc.DriverType=thin
jdbc.InactivityTimeout=1800
jdbc.InitialLimit=3
jdbc.MaxConnectionReuseCount=1000
jdbc.MaxLimit=10
jdbc.MaxStatementsLimit=10
jdbc.MinLimit=1
jdbc.statementTimeout=900
log.logging=false
log.maxEntries=50
misc.compress=
misc.defaultPage=apex
security.disableDefaultExclusionList=false
security.maxEntries=2000
May 07, 2018 3:48:02 AM
WARNING: *** jdbc.MaxLimit in configuration |apex|pu| is using a value of 10, this setting may not be sized adequately for a production environment ***
May 07, 2018 3:48:02 AM
WARNING: *** jdbc.InitialLimit in configuration |apex|pu| is using a value of 3, this setting may not be sized adequately for a production environment ***
May 07, 2018 3:48:02 AM
INFO: Oracle REST Data Services initialized
Oracle REST Data Services version : 18.1.1.95.1251
Oracle REST Data Services server info: jetty/9.4.z-SNAPSHOT
2018-05-07 03:48:02.710:INFO:oejsh.ContextHandler:main: Started o.e.j.s.ServletContextHandler@48eff760{/ords,null,AVAILABLE}
2018-05-07 03:48:02.711:INFO:oejsh.ContextHandler:main: Started o.e.j.s.h.ContextHandler@402f32ff{/,null,AVAILABLE}
2018-05-07 03:48:02.711:INFO:oejsh.ContextHandler:main: Started o.e.j.s.h.ContextHandler@573f2bb1{/i,null,AVAILABLE}
2018-05-07 03:48:02.721:INFO:oejs.AbstractNCSARequestLog:main: Opened /tmp/ords_log/ords_2018_05_07.log
2018-05-07 03:48:02.755:INFO:oejs.AbstractConnector:main: Started ServerConnector@2aece37d{HTTP/1.1,[http/1.1, h2c]}{0.0.0.0:8888}
2018-05-07 03:48:02.755:INFO:oejs.Server:main: Started @3576ms
Now that ORDS is up and running, you can start REST-enabling your database. Note that all configuration files are within a volume, in my case -v /home/oracle/ords:/opt/oracle/ords/config/ords:rw. If you would like to change any of the ORDS configuration, you can just do so in the volume and then restart the container, if needed.
Gerald on IT 
Really good write up and detailed instructions about Docker. A shorter version with just the Docker info (and no need to build Oracle JRE) can be found: https://github.com/martindsouza/docker-ords
LikeLike
hello,
when executing the command:
docker run –name ords -p 8888:8888 –network=ords-database-network -e ORACLE_HOST=ords-db -e ORACLE_PORT=1521 -e ORACLE_SERVICE=ORCLPDB1 -e ORACLE_PWD=Oradoc_db1 -e ORDS_PWD=LetsORDS -v /home/oracle/ords:/opt/oracle/ords/config/ords:rw oracle/restdataservices:18.1.1
I get the following error
mkdir: cannot create directory ‘/opt/oracle/ords/config/ords/standalone’: Permission denied
cp: cannot create regular file ‘/opt/oracle/ords/config/ords/standalone/standalone.properties’: No such file or directory
sed: can’t read /opt/oracle/ords/config/ords/standalone/standalone.properties: No such file or directory
sed: can’t read /opt/oracle/ords/config/ords/standalone/standalone.properties: No such file or directory
sed: can’t read /opt/oracle/ords/config/ords/standalone/standalone.properties: No such file or directory
Aug 23, 2019 10:09:18 PM
SEVERE: Error writing to: /opt/oracle/ords/config/ords/defaults.xml, /opt/oracle/ords/config/ords/defaults.xml (Permission denied)
Could not invoke: oracle.dbtools.injector.impl.InstantiatorsImpl$ReflectiveInstantiator@6cd8737, due to the following error: oracle.dbtools.common.UnrecoverableException: /opt/oracle/ords/config/ords/defaults.xml (Permission denied)
/opt/oracle/ords/config/ords/standalone
help me !!
LikeLike
Hi Rtrejo,
The container doesn’t have permissions to write to
/home/oracle/ords.Please give write permissions to it.
Thx,
LikeLike
Thanks Gerald,
This is easy to get up and running, but I’m not sure what to do next. Is there a ‘hello-world’ tutorial that picks up where this leaves off?
LikeLike
Hi Taqui,
You want to check out Jeff Smith’s blog and GitHub repo for examples: https://www.thatjeffsmith.com/archive/2018/01/oracle-rest-data-services-github-all-the-examples/
Thanks,
LikeLike
Thanks for the quick reply!
all the documentation I’ve read explains how to install ords from sql developer onto your local workstation. I’m not sure where the ORDS container fits into anything. When i hit the :8888 endpoint it returns 403, when hitting :8888/ords it gives 404.
If I get this docker image to work I’ll be sure to post an update. Cheers
LikeLike
Hi Taqui,
Once the ORDS container is up and running, you will have to REST enable the schemas you want to expose. For example, to enable the
TESTuser, you have to run this:DECLARE PRAGMA AUTONOMOUS_TRANSACTION; BEGIN ORDS.ENABLE_SCHEMA(p_enabled => TRUE, p_schema => 'TEST', p_url_mapping_type => 'BASE_PATH', p_url_mapping_pattern => 'test', p_auto_rest_auth => FALSE); commit; END;Once that is done, you can start accessing REST enabled objects, for example:
http://localhost:8888/ords/test/metadata-catalog/Thx,
LikeLike