Oracle recently launched a new GitHub repository for providing people with Oracle software inside Vagrant boxes. If you have ever setup 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.
What you need
- Oracle VirtualBox installed on your machine
- Vagrant installed on your machine
- The Oracle install zip files, you can download them from the Oracle Technology Network
- The Vagrant configuration files from GitHub, you can download or clone the repository
Setup
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.
Creating an Oracle Database Vagrant box
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
Using the database inside the VM
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 ~]$
Stopping and restarting the VM
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$
Destroying/deleting the VM
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.
Conclusion
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.
Gerald on IT 
Could you elaborate on how to use the Vagrantfile config.vm.provision section to run scripts that are able to create a new user/schema in the database and insert reference data ?
I have tryed to make vagrant run a script in the guest (at vagrant up time) but problems arise because the vagrant user do not have sqlplus in the PATH and because making sudo su -p oracle -c “sqlplus / as sysdba etc, etc” (as inspired by the setPassword.sh) doesn’t work either.
Thanks.
LikeLike
Hey Pascal,
You should be able to just put your script into scripts/ and then amend install.sh to call it at the end of the installation. Or you can just add whatever you want to do into install.sh directly. Note that install.sh is executed as root, so you can/have to do a “su -l oracle -c” as we do it with the other commands that have to run as the oracle user (dbca, runInstaller, etc).
Hope this helps!
Thx,
LikeLike
Gerald,
Are you sure the scripts are executed as root user? Isn’t it as vagrant user?
Anyway as you say, the user executing the scripts (be it root or vagrant) do not have sqlplus in its PATH.
The fix I found was to start my script with the following line to switch from the current user to the oracle user:
[ `whoami` = oracle ] || exec sudo su – oracle -c /vagrant/scripts/init_my_db.sh
Note that I had to use sudo su – oracle and not su -l oracle it might make the difference.
Thx.
LikeLike
Hey Pascal,
I’m fairly certain that it’s the root user as yum is executed three times inside install.sh and yum can only be run as root (see https://github.com/oracle/vagrant-boxes/blob/master/OracleDatabase/18.3.0/scripts/install.sh#L33 for example).
I’m glad that you could solve it. 🙂
Thx,
LikeLike
Hi Gerald,
Thanks for this article. Saved me a lot of time and effort. I had to a couple of thing to get this to work. The first was to download the latest version of Vagrant. I already had the latest version VirtualBox installed on my Mac. The next I needed to do was to download the database zip package from the Oracle e-delivery website since its an older version. The ZIP file name format of the Oracle Database package, especially if you’re trying to work with an older version, as in my case below, get’s downloaded as such: V839960-01.zip.
When placing this file as-is under vagrant-projects/OracleDatabase/12.2.0.1, I recieved the below error:
oracle-12201-vagrant: INSTALLER: Environment variables set
oracle-12201-vagrant: unzip: cannot find or open /vagrant/linux122.zip, /vagrant/linux122.zip.zip or /vagrant/linux122.zip.ZIP.
oracle-12201-vagrant: No zipfiles found.
The SSH command responded with a non-zero exit status. Vagrant
assumes that this means the command failed. The output for this command
should be in the log above. Please read the output to determine what
went wrong.
….So, I copied the file to a filename to the format the installer expects at the command prompt:
Bal@Balvinders-MacBook-Pro 12.2.0.1 % cp V839960-01.zip linux_12201.zip
oracle-12201-vagrant: INSTALLER: Environment variables set
oracle-12201-vagrant: Archive: /vagrant/linux_12201.zip
oracle-12201-vagrant: creating: /tmp/database/
oracle-12201-vagrant: creating: /tmp/database/sshsetup/
oracle-12201-vagrant: inflating: /tmp/database/sshsetup/sshUserSetup.sh
oracle-12201-vagrant: creating: /tmp/database/rpm/
oracle-12201-vagrant: inflating: /tmp/database/rpm/cvuqdisk-1.0.10-1.rpm…..
Everything was plain sailing from that point onwards.
Thanks,
Bal
LikeLike
Thanks for sharing your experience, Bal!
Indeed, as time moves on and versions go out of support, these instructions may not match exactly anymore.
I’m glad to hear that you could get it up and running in the end! 🙂
Thx,
LikeLike
Gerald, this is a great how-to, thanks for posting. I followed it over a year ago to get Oracle DB running in a VM. When I start that VM, Vagrant is now telling me
“A newer version of the box ‘oraclelinux/8’ is available and already installed, but your Vagrant machine is running against version ‘8.6.359’. To update to version ‘8.7.411’, destroy and recreate your machine.”
I’m hoping to preserve the database created in the old machine, but I don’t really know much about Vagrant. Would be great if you could add some instructions to follow when upgrading the box version.
LikeLike
Hey Guy,
Thanks a lot, glad you find it useful!
Hm, destroying the machine will for sure also wipe out the database inside it. However, you could export your database or unplug your PDB and copy it on your actual computer, and afterwards reimport or plug the PDB back in.
Alternatively, you could just update Linux inside the VM directly too!
Thanks,
LikeLike
Thanks for the reply. I decided to keep things simple, and just script everything I apply to the database in the VM. Then, after an upgrade, I can reapply the scripts. Hopefully this Q&A might help others that find themselves in this situation and are unsure how to proceed. The important thing to know is that applying an update will not magically preserve your database; you must do this manually yourself.
Also, regarding: “First you will have to download the Oracle Database installer zip file onto your local machine.” I decided to upgrade to newer Oracle Database version (and also newer OS.) I went with 21.3.0-XE. I discovered that with this version, I did not have to download the database zip file separately. The initial “vagrant up” command downloaded it automatically and installed it. I reported this to the maintainers of vagrant-projects on GitHub, and they said they would add some clarifying language.
LikeLiked by 1 person
Hey Guy,
Scripting it is probably the best and certainly a future-proof approach.
Oh great, thanks for that!
Gerald
LikeLike