No description, website, or topics provided.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Docker_Kscope2018_05.12.18.key
README.md
install_apexpdb181.sh
install_apexpdb514.sh

README.md

Launch APEX with Docker

Intro

Docker is a radical way to host an Oracle APEX environment on your computer that:

  1. minimizes the strain you impose on your system’s memory
  2. maximizes your potential to version and share your database configuration.

This post was made to support of a youtube video I made. In this post, I’m going to cover the details of running the latest version of APEX from scratch on your computer, using Docker.

References

All of my code has been assembled from the following sources:

Ingredients

APEX

hayden@mac:~/docker$ mkdir apex
hayden@mac:~/docker$ cd apex/
hayden@mac:~/docker/apex$ mv ~/Downloads/apex_18.1.zip .
hayden@mac:~/docker/apex$ unzip apex_18.1.zip
[...]
ayden@mac:~/docker/apex$ mv apex 18.1.0
  • Download my database configuration script: install_apex181.sh and move it to the directory you just created ~/docker/apex/. Make sure you replace the email on line 37 with your own email.
hayden@mac:~/docker/apex/18.1.0$ mv ~/Downloads/install_apex181.sh .

ORDS

We need 2 things for Oracle Rest Data Service too

  • Git clone Martin D'Souza's git repo in the path ~/docker/ords/
hayden@mac:~/docker/ords$ git clone https://github.com/martindsouza/docker-ords.git .
hayden@mac:~/docker/ords$ mv ~/Downloads/ords.17.4.1.353.06.48.zip .
hayden@mac:~/docker/ords$ unzip ords.17.4.1.353.06.48.zip

Docker

  • Make sure that Docker installed on your computer.
hayden@mac:~/docker$ docker version
Client:
 Version:	18.03.0-ce
 ...
  • Visit store.docker.com to accept the Oracle terms and conditions for using their database image:
    1. login
    2. search for 'oracle enterprise edition'
    3. agree to the terms and conditions.

Create the oracle container

Now that we have all of these prerequisites assembled, let’s start by kicking off your Oracle database and installing the latest version of APEX.

2 small pieces of configuration

  1. Create a an empty folder called ‘oracle’ in the path ~/docker. You are going to mount to this folder to your docker container so that all database configuration gets stored in this folder. This is not a requirement but it gives you some options to share your configuration with your team-mates, as we will discuss:
hayden@mac:~/docker$ mkdir oracle
  1. Create a docker network. I’m going to call it ‘oracle_network’. This will permit your containers to easily talk with one another.
hayden@mac:~$ docker network create oracle_network

Container command

hayden@mac:~$ docker run -d -it \
--name oracle \
-p 32122:1521 \
-e TZ=America/New_york \
--network=oracle_network \
-v ~/docker/oracle:/ORCL \
-v ~/docker/apex/18.1.0:/tmp/apex \
store/oracle/database-enterprise:12.2.0.1

Let's walk through this command -

  1. You’ve given this container the name ‘oracle’, which means other containers on the ‘oracle_network’ can refer to it by this name You map the container’s database port 1521 to external port 32122.
  2. You set the timezone to your own.
  3. You instruct it to listen on the network you’ve created, 'oracle_network'.
  4. As I touched on earlier, you then map your local folder structure ~/docker/oracle to the container’s folder /ORCL. all the database configuration will be stored here. This is a good idea because, after you’ve done all that you want with the database, you can simply zip and share the contents of this folder with your teammates, thereby sparing them from having to repeat your work.
  5. You also mount the local folder ~/docker/apex to the container.
  6. The last line in this ‘docker run’ command refers to the official oracle database image on the docker repository. This will work if you’ve already accepted their license agreement on store.docker.com

Depending on the processing power of your computer, your oracle container may take over 5 minutes to start up. In the background, know that a ton of configuration scripts are being run inside your container, building the database and populating your mounted ~/docker/oracle folder with around 6GB worth of configuration files.

You can check the status of your container with the command:

hayden@mac:~$ docker ps
CONTAINER ID        IMAGE                                       COMMAND                  CREATED             STATUS                        PORTS                               NAMES
221b75906a65        store/oracle/database-enterprise:12.2.0.1   "/bin/sh -c '/bin/ba…"   12 days ago         Up About a minute (healthy)   5500/tcp, 0.0.0.0:32122->1521/tcp   oracle

Run database configuration script (install APEX)

Once the oracle container has a status of 'healthy', you can log in and configure it to where you want it to be. Fair warning: while this step isn’t complicated, it could easily take over 20 minutes.

The configuration is easy to kick-off:

  1. Log into the container
  2. Navigate to the mounted folder that contains the configuration files for the latest version of APEX
  3. Make my configuration script executable (we moved it to this folder earlier)
  4. Run the script
hayden@mac:~$ docker exec -it oracle bash
[oracle@221b75906a65 /]$ cd /tmp/apex/
[oracle@221b75906a65 apex]$ chmod +x install_apexpdb181.sh
[oracle@221b75906a65 apex]$ ./install_apexpdb181.sh

Let's walk through the commands in this script:

@apxremov.sql;

You start by 1st removing the existing APEX installation in the container database. This is necessary if you want to create a pluggable database (or pdb) that does not have APEX preinstalled.

create pluggable database orclpdb181 admin user pdb_adm identified by Oradoc_db1
file_name_convert=('/u02/app/oracle/oradata/ORCL/pdbseed/','/u02/app/oracle/oradata/ORCL/ORCLPDB181/');

You then proceed to create a new pdb with 181 in the name because we plan to install APEX 18.1.

alter pluggable database orclpdb181 open read write;
alter pluggable database all save state;

You open the pdb.

Alter session set container = ORCLPDB181;
@apexins.sql SYSAUX SYSAUX TEMP /i/;

You install APEX 18.1 in the new pdb - - this step takes a while

@apex_rest_config_core.sql oracle oracle;
alter session set container = CDB\$ROOT;
alter user apex_public_user identified by oracle account unlock;

Finally, you configure APEX to communicate with ORDS

Alter session set container = ORCLPDB181;
declare
    l_acl_path varchar2(4000);
    l_apex_schema varchar2(100);
begin
    for c1 in (select schema
                 from sys.dba_registry
                where comp_id = 'APEX') loop
        l_apex_schema := c1.schema;
    end loop;
    sys.dbms_network_acl_admin.append_host_ace(
        host => '*',
        ace => xs\$ace_type(privilege_list => xs\$name_list('connect'),
        principal_name => l_apex_schema,
        principal_type => xs_acl.ptype_db));
    commit;
end;
/

2 final pieces of configuration - You configure your ACL privileges

begin
    apex_util.set_security_group_id( 10 );
    apex_util.create_user(
        p_user_name => 'ADMIN',
        p_email_address => 'you@youremail.com',
        p_web_password => 'Oradoc_db1',
        p_developer_privs => 'ADMIN',
        p_change_password_on_first_use => 'N');
    apex_util.set_security_group_id( null );
    commit;
end;
/

And you create an admin user to log into APEX - I hope you remembered to switch out the placeholder email here.

Create the ORDS container

Build the ORDS image

While the previous step is cooking, you can start to prepare a 2nd container for our Oracle Rest Data Services. There is currently no Oracle ORDS official Docker image in the repository but with the ingredients you assembled in your ~/docker/ords folder at the top of this tutorial, you can easily build the requisite image yourself and then, if you like, share it with your teammates by pushing it your docker hub. To build the requisite ORDS image, navigate to your docker/ords folder and run this docker build command

hayden@mac:~/docker/ords$ docker build -t ords:3.0.12 .

Upon successful completion, you’ll find an image with the name ords in your docker images.

If you want to spare your teammates from the minor inconvenience of downloading the latest version of ORDS and cloning Martin D’Souza’s git repository as we did at the top of the video, you can push this image to your docker hub with the commands:

haydenhudson@Haydens-MacBook-Air:~$ docker images | grep ords
ords                               3.0.12              06b3950c1d58        12 days ago         193MB

hayden@mac:~/docker push haydenhhudson/ords:3.0.12

I’d offer to share my own with you but doing so may violate Oracle’s terms and conditions.

Run the ORDS container

For this final step - You’ll want to wait for your apex installation script to complete before going further. In this step, you’ll spin up your ORDS container that will talk to your Oracle database and finally be able to access your APEX web interface.

hayden@mac:~$ docker run -t -i \
  --name ords_181 \
  --network=oracle_network \
  -e TZ=America/New_york \
  -e DB_HOSTNAME=oracle \
  -e DB_PORT=1521 \
  -e DB_SERVICENAME=orclpdb181.localdomain \
  -e APEX_PUBLIC_USER_PASS=oracle \
  -e APEX_LISTENER_PASS=oracle \
  -e APEX_REST_PASS=oracle \
  -e ORDS_PASS=oracle \
  -e SYS_PASS=Oradoc_db1 \
  --volume ~/docker/apex/18.1.0/images:/ords/apex-images \
  -p 32181:8080 \
  ords:3.0.12

Let’s walk through this command

  1. You name the container ords_181 to match the name of the oracle pluggable database and APEX version because that gives the option to simultaneously spin up other ords containers that serve up different APEX installations on different pdbs in your multitenant oracle database. Next time you want to start this container, to state the possibly obvious, you’d simply run docker start ords_181
  2. As before, you place this container on the oracle_network that you created so that it can communicate with the oracle container. You set the appropriate timezone
  3. Next, we pass in some configuration property values necessary for the ords installation.
  4. You identify the name of the db_hostname to match the name of your db container
  5. You let ords know that it should communicate with the db on port 1521
  6. You instruct this installation of ords to listen for the pdb that we specially configured with the latest version of APEX You then pass in the appropriate values for the passwords for the database users APEX_PUBLIC_USER, APEX_LISTENER, APEX_REST, ORDS and SYS
  7. You mount the local apex images folder so that ORDS can serve them up appropriately 1.You map the container’s port 8080 to port 32181 so you can access it in your browser on port 32181
  8. Finally you instruct your container to build on the docker image that you built

After running this command and getting no error messages, we can now switch to a browser to confirm that we’re done: http://localhost:32181/ords

You can now log into your APEX Internal workspace with the values set by the APEX installation script you ran earlier: username ADMIN, password Oradoc_db1.

Share and version your work

Don’t forget - your work can be leveraged for the benefit your colleagues to spare them some of the heavy lifting your just did. if you

  1. share the contents of your ~/docker/oracle folder
  2. push your ords image to your docker hub

For your colleagues this would mean:

  • No downloading ORDS
  • No cloning Martin D’Souza’s git repo
  • No performing any configuration on the oracle container, including installing APEX.

Suggestion

  • Use a private github repo and pay for additional space. With Git LFS and $5/month you can buy 50gb worth of space and preserve a library of database snapshots that you and your team mates can clone into your ~/docker/oracle folder.
    • With this setup the docker command for spinning up the Oracle container for the 1st time would be the same but, the execution would be faster because the docker container would not need to build the database.

Disclaimer

All of these recommendations are of subject to the constraints of your Oracle License agreement.

Next steps

I have collected some thoughts on how to use your freshly minted Oracle APEX Dev environment and collaborate with your colleages in the following blog post.