Creating an Oracle Database Vagrant Box

Oracle recently launched a new GitHub repository for providing people with Oracle software inside Vagrant boxes. If you have ever set up an Oracle database inside a VirtualBox VM, whether it is as your sandbox environment, to explore Oracle database, or to use it as a full-on development environment, things have just gotten a lot easier for you. With Vagrant, you can now provision an Oracle database inside VirtualBox in a matter of a couple of simple steps.

1. Oracle VirtualBox installed on your machine
2. Vagrant installed on your machine
3. The Oracle install zip files, you can download them from the Oracle Technology Network
4. The Vagrant configuration files from GitHub, you can download or clone the repository

I'm not going to cover the VirtualBox nor Vagrant setup as those are really simple but also depend on the platform you are using. You can find the VirtualBox installation instructions in the VirtualBox Installation documentation. Likewise, you can find the Vagrant installer on the Vagrant Downloads page.

After you have setup VirtualBox and Vagrant in your environment successfully you can now go ahead and create an Oracle Database Vagrant box. First you will have to download the Oracle Database installer zip file onto your local machine. You will need to download the Linux x86-64 zip file of the version you would like to build, in my case 12.2.0.1. Once you have done that, it is time to clone/download the GitHub repository:

gvenzl-mac:vagrant gvenzl$ git clone https://github.com/oracle/vagrant-boxes
Cloning into 'vagrant-boxes'...
remote: Counting objects: 74, done.
remote: Total 74 (delta 0), reused 0 (delta 0), pack-reused 74
Unpacking objects: 100% (74/74), done.

Next, you will have enter the vagrant-boxes/OracleDatabase/<version> folder of the version you would like to build and then copy the Oracle Database installer zip file into the folder:

gvenzl-mac:vagrant gvenzl$ cd vagrant-boxes/OracleDatabase/12.2.0.1/
gvenzl-mac:12.2.0.1 gvenzl$ cp ~/Downloads/linuxx64_12201_database.zip .

Now you are ready to build the Vagrant box. During the installation the scripts will update Linux inside the VM to the latest and greatest, as well as install all required packages for the Oracle database, so make sure that you have internet connectivity! In order to get the creation of the VM started, all you have to do is to type vagrant up and then wait for its completion:

gvenzl-mac:12.2.0.1 gvenzl$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Box 'http://yum.oracle.com/boxes/oraclelinux/latest/ol7-latest.box' could not be found. Attempting to find and install...
default: Box Provider: virtualbox
default: Box Version: >= 0
==> default: Box file was not detected as metadata. Adding it directly...
==> default: Adding box 'http://yum.oracle.com/boxes/oraclelinux/latest/ol7-latest.box' (v0) for provider: virtualbox
default: Downloading: http://yum.oracle.com/boxes/oraclelinux/latest/ol7-latest.box
==> default: Successfully added box 'http://yum.oracle.com/boxes/oraclelinux/latest/ol7-latest.box' (v0) for 'virtualbox'!
==> default: Importing base box 'http://yum.oracle.com/boxes/oraclelinux/latest/ol7-latest.box'...
==> default: Matching MAC address for NAT networking...
==> default: Setting the name of the VM: oracle-12201-vagrant
==> default: Clearing any previously set network interfaces...
==> default: Preparing network interfaces based on configuration...
default: Adapter 1: nat
==> default: Forwarding ports...
default: 1521 (guest) => 1521 (host) (adapter 1)
default: 5500 (guest) => 5500 (host) (adapter 1)
default: 22 (guest) => 2222 (host) (adapter 1)
==> default: Running 'pre-boot' VM customizations...
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
default: SSH address: 127.0.0.1:2222
default: SSH username: vagrant
default: SSH auth method: private key
default:
default: Vagrant insecure key detected. Vagrant will automatically replace
default: this with a newly generated keypair for better security.
default:
default: Inserting generated public key within guest...
default: Removing insecure key from the guest if it's present...
default: Key inserted! Disconnecting and reconnecting using new SSH key...
==> default: Machine booted and ready!
...
...
...
==> default: Creating Pluggable Databases
==> default: 55% complete
==> default: 75% complete
==> default: Executing Post Configuration Actions
==> default: 100% complete
==> default: Look at the log file "/opt/oracle/cfgtoollogs/dbca/ORCLCDB/ORCLCDB.log" for further details.
==> default:
==> default: SQL*Plus: Release 12.2.0.1.0 Production on Fri Feb 9 23:02:02 2018
==> default:
==> default: Copyright (c) 1982, 2016, Oracle. All rights reserved.
==> default:
==> default: Connected to:
==> default: Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production
==> default: SQL>
==> default: Pluggable database altered.
==> default: SQL>
==> default: Disconnected from Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production
==> default: INSTALLER: Database created
==> default: INSTALLER: Oratab configured
==> default: Created symlink from /etc/systemd/system/multi-user.target.wants/oracle-rdbms.service to /etc/systemd/system/oracle-rdbms.service.
==> default: INSTALLER: Created and enabled oracle-rdbms systemd's service
==> default: INSTALLER: setPassword.sh file setup
==> default: ORACLE PASSWORD FOR SYS, SYSTEM AND PDBADMIN: VIxtcphKIQs=1
==> default: INSTALLER: Installation complete, database ready to use!

On successful completion of the creation you will see the message: INSTALLER: Installation complete, database ready to use! Furthermore, you will also get to see the automatically generated password for the administrative accounts inside the database (more on password defaults and resets further below), in my case: ORACLE PASSWORD FOR SYS, SYSTEM AND PDBADMIN: VIxtcphKIQs=1

Once the provisioning is complete, you can now carry on and use the database inside your VM. There are several ways of doing so, all geared towards making your life easier.

Use SSH to Get Inside of the VM

Vagrant allows you to ssh into the virtual machine just like as it would be any random Linux server within your network. If you are command line savvy and this is all you need, you can do a simple vagrant ssh to get a terminal inside the VM. You will be logged on as the vagrant Linux user who has sudo rights to execute any privileged command:

gvenzl-mac:12.2.0.1 gvenzl$ vagrant ssh

Welcome to Oracle Linux Server release 7.4 (GNU/Linux 4.1.12-112.14.13.el7uek.x86_64)

The Oracle Linux End-User License Agreement can be viewed here:

* /usr/share/eula/eula.en_US

For additional packages, updates, documentation and community help, see:

* http://yum.oracle.com/

[vagrant@oracle-12201-vagrant ~]$ sudo su - oracle
Last login: Thu May 24 06:19:28 UTC 2018 on pts/0
[oracle@oracle-12201-vagrant ~]$ sqlplus / as sysdba

SQL*Plus: Release 12.2.0.1.0 Production on Thu May 24 06:20:20 2018

Copyright (c) 1982, 2016, Oracle. All rights reserved.

Connected to:
Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production

SQL>

Connecting Directly via Port-Forwarding

The Vagrant box automatically sets up port forwarding between the VirtualBox VM and your host. Port forwarding is a technique VirtualBox uses where it will automatically forward all traffic on a given port to the port on the other side. The very nice thing about this technique is that it allows you to continue to use your local dev tools installed on your laptop and connect them to the database inside the VM! For example, you can connect your local SQL Developer or SQLcl to the database inside the VM just like you would connect to any other database in your network. The only trick to remember is to connect to localhost, for example:

The Vagrant VM is automatically setup to forward the port 1521 on your host to port 1521 inside your VM. That means that if you have anything that will open and talk to port 1521 on your localhost, say SQLcl, it will automatically be forwarded to port 1521 inside the VM where there happens to be an Oracle database listener waiting for incoming traffic. The same is true for port 5500. If you will open your browser and navigate to https://localhost:5500/em your browser's traffic will be forwarded to port 5500 inside the VM where you have OEM Express waiting to serve your browser.

gvenzl-mac:12.2.0.1 gvenzl$ sql system@//localhost:1521/ORCLCDB

SQLcl: Release 18.1.1 Production on Wed May 23 23:24:43 2018

Copyright (c) 1982, 2018, Oracle. All rights reserved.

Password? (**********?) *************
Last Successful login time: Wed May 23 2018 23:24:45 -07:00

Connected to:
Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production

SQL> exit

Disconnected from Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production
gvenzl-mac:12.2.0.1 gvenzl$

Resetting the Database Passwords

By default the passwords for the SYS, SYSTEM and PDBADMIN user are all the same autogenerated password printed into the output after the setup has finished. You can of course just use that password going forward or you may wish to reset it to something more memorable. The VM provides a simple setPassword.sh shell script that will allow you to reset all the passwords at once to a password of your choice. Simply call /home/oracle/setPassword.sh <your new password> and the rest will be done for you:

gvenzl-mac:12.2.0.1 gvenzl$ vagrant ssh
Last login: Thu May 24 06:25:54 2018 from 10.0.2.2

Welcome to Oracle Linux Server release 7.4 (GNU/Linux 4.1.12-112.14.13.el7uek.x86_64)

The Oracle Linux End-User License Agreement can be viewed here:

* /usr/share/eula/eula.en_US

For additional packages, updates, documentation and community help, see:

* http://yum.oracle.com/

[vagrant@oracle-12201-vagrant ~]$ sudo su - oracle
Last login: Thu May 24 06:26:53 UTC 2018 on pts/0
[oracle@oracle-12201-vagrant ~]$ ./setPassword.sh LetsVagrant
The Oracle base remains unchanged with value /opt/oracle

SQL*Plus: Release 12.2.0.1.0 Production on Thu May 24 06:27:42 2018

Copyright (c) 1982, 2016, Oracle. All rights reserved.

Connected to:
Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production

SQL>
User altered.

SQL>
User altered.

SQL>
Session altered.

SQL>
User altered.

SQL> Disconnected from Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production
[oracle@oracle-12201-vagrant ~]$ sqlplus system/LetsVagrant@ORCLPDB1

SQL*Plus: Release 12.2.0.1.0 Production on Thu May 24 06:27:56 2018

Copyright (c) 1982, 2016, Oracle. All rights reserved.

Last Successful login time: Thu May 24 2018 06:24:45 +00:00

Connected to:
Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production

SQL> exit
Disconnected from Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production
[oracle@oracle-12201-vagrant ~]$

If you would like to stop the VM you can just type a simple vagrant halt command:

gvenzl-mac:12.2.0.1 gvenzl$ vagrant halt
==> default: Attempting graceful shutdown of VM...
gvenzl-mac:12.2.0.1 gvenzl$ vagrant ssh
VM must be running to open SSH connection. Run `vagrant up`
to start the virtual machine.
gvenzl-mac:12.2.0.1 gvenzl$

Likewise, if you want to start the VM again, you just use the vagrant up command again. This time Vagrant will detect that the VM is already there and just start it up:

gvenzl-mac:12.2.0.1 gvenzl$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Clearing any previously set forwarded ports...
==> default: Clearing any previously set network interfaces...
==> default: Preparing network interfaces based on configuration...
default: Adapter 1: nat
==> default: Forwarding ports...
default: 1521 (guest) => 1521 (host) (adapter 1)
default: 5500 (guest) => 5500 (host) (adapter 1)
default: 22 (guest) => 2222 (host) (adapter 1)
==> default: Running 'pre-boot' VM customizations...
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
default: SSH address: 127.0.0.1:2222
default: SSH username: vagrant
default: SSH auth method: private key
==> default: Machine booted and ready!
==> default: Checking for guest additions in VM...
==> default: Setting hostname...
==> default: Mounting shared folders...
default: /vagrant => /Users/gvenzl/Downloads/vagrant/vagrant-boxes/OracleDatabase/12.2.0.1
==> default: Machine already provisioned. Run `vagrant provision` or use the `--provision`
==> default: flag to force provisioning. Provisioners marked to run always will still run.
gvenzl-mac:12.2.0.1 gvenzl$ vagrant ssh
Last login: Thu May 24 06:27:34 2018 from 10.0.2.2

Welcome to Oracle Linux Server release 7.4 (GNU/Linux 4.1.12-112.14.13.el7uek.x86_64)

The Oracle Linux End-User License Agreement can be viewed here:

* /usr/share/eula/eula.en_US

For additional packages, updates, documentation and community help, see:

* http://yum.oracle.com/

[vagrant@oracle-12201-vagrant ~]$ exit
logout
Connection to 127.0.0.1 closed.
gvenzl-mac:12.2.0.1 gvenzl$

If you no longer need the VM you can easily remove it via the vagrant destroy command. This command will remove the VM and all files associated with it from your machine. The command works regardless whether the VM running or not, so be cautious:

gvenzl-mac:12.2.0.1 gvenzl$ vagrant destroy
default: Are you sure you want to destroy the 'default' VM? [y/N] y
==> default: Forcing shutdown of VM...
==> default: Destroying VM and associated drives...
gvenzl-mac:12.2.0.1 gvenzl$

Note that once vagrant destroy has been executed a vagrant up will provision a new VM for you again.

Vagrant is a great tool to simplify VirtualBox VM (and many more) creation. By just using simple one line commands you can create, start, resume, suspend, stop, and destroy VMs without having to know all the complex provisioning steps.