There are 3 motivations behind this article, as a consultant or software developer I have projects in different APEX versions and one issue that I have is that I don’t have enough space on my laptop for all virtual machines, so I start using externa hard disks and always switching between them.

Second motivation is to reduce the time spent with creating the needed project infrastructure before really start working on the project, ideally for me would be to start with the project as soon as possible, so reducing the time spent for creating the project infrastructure is important for me.

Third motivation has its roots in the centralized way of how APEX projects are developed, this means that I would like to be able to work and experiment on my development machine and not use a central APEX deployment for development for all developers.


To achieve all this I’m using a combination of Vagrant and Docker, where Vagrant helps me to create an Oracle Virtual Box, from a provision script, and Docker helps me to create the necessary containers for the project infrastructure. On a basic APEX project, I would have had an Oracle Database container with the database version and with the APEX version required by my project, so that is the base. In addition to Oracle Database and APEX I need to adjust the Vagrant provision script with other docker commands to pull the required images and instantiate the containers.


For this article I would use Keycloak to provide an OAuth2 authentication to my APEX application. From APEX 18.1 on we have this Social Sign-In option for the authentication schemas, which I will use to configure an OAuth2 authentication. I’m using Docker to create the Oracle Database container, to upgrade APEX to version 18.1 or 18.2, to install my APEX application and to create the Keycloak container.

The scripts and the project can be downloaded from this GitHub repository: .

The DOAG presentation can be downloaded from here: Using Vagrant and Docker for APEX development 2018_V1.0-DOAG


  1. Vagrant provisioning script
  2. Using Docker
  3. Keycloak configuration
  4. Upgrade APEX – use case
  5. Upgrade Application – use case

Vagrant provisioning script

For setting up Vagrant, I’m using the base image “ol73” (Oracle Linux 7.3), so before running “vagrant up” I must import this box by the following command:

vagrant box add --name ol73

After you executed this command you just must run “vagrant up” so that the provisioning of the virtual machine is started, after some time you will have the following project infrastructure:

Have a look on the vagrant file provide in this GitHub project: There are some important things to be noted in the vagrant file, like:

  • The ports exposed to the external environment by the created virtual box; "forwarded_port", guest: 1521, host: 1522 "forwarded_port", guest: 8080, host: 8080
  • Configuration for storage and memory;
  • And the provision script, where the magic happens, installing docker, importing docker images and creating the containers, etc;

Using Docker

After we used Vagrant to provide the basic needs in my virtual machine, I’ll use docker to achieve the followings:

  • Install oracle database
  • Upgrade APEX from a GIT repository
  • Install Application froma GIT repository
  • Install Keycloack

You can have a look in the vagrant provision script here, in the section where it is described the provisioning, starting with: config.vm.provision “shell”.

The installed APEX application is containing all the needed configuration and setup to enable the Sign-In authentication using keycloak, this means I have the following:

  • Web credentials with the client key and the client secret;
  • The Database ACL is configured to allow Database HTTP/HTTPS connections to keycloak host;

The authentication schema is setup with the authorization url, token url and user detail information url;

Keycloak configuration

After the installation of keycloak is done, using docker container, I must create a realm and users, fortunately all this can be done by importing the files provided in the git repository:

Upgrade APEX – use case

So now that we have provisioned the project infrastructure, I can use the following command to upgrade/downgrade my APEX installation to 18.1 or 18.2:

vagrant --action=upgrade_apex --apex-version=18.2 up


vagrant --action=upgrade_apex --apex-version=18.1 up

This will do a “job” docker container which will trigger all the installation steps, after the installation is finished the container is destroyed.

Upgrade Application – use case

Also, I can sync my APEX application code with GIT, when there are changes I can install them using the following command:

vagrant --action=upgrade_app up

Similar to the upgrade of APEX mechanism, the above command will do a “job” docker container which will trigger all the installation steps for the application, followed by the container destruction.


Using provisioning scripts to build project infrastructure has many benefits, it allows the team to focus on the project and not on the infrastructure, enables decentralized development (eventually nearshoring development), reduce the time to setup the project infrastructure and provides the same basis for all developers.