Setting Up Oracle Commerce on Mac OSX

Oracle/ATG development has historically been dominated by Windows machines.  There have been a small number of people migrating over onto Mac OSX because, well, Apple makes a great computer for development.  Oracle and ATG have been slow to catch on to the users migrating over to Apple, and haven’t begun officially supporting an OSX ATG release (yet).
Even though running Oracle ATG Web Commerce on your mac is unsupported, it is very stable and very easy to do.  There are only two drawbacks to developing with ATG on OSX.  First, Search doesn’t work. In perspective, Search development is a fairly small chunk of the ATG platform.  If you absolutely need it, there are workarounds.  Second, the ‘traditional’ database of ATG – Oracle, does not work on OSX (yet).  An easy workaround will be discussed further down.


1. A supported application server installed and configured.

2. Basic unix terminal knowledge.


1. First, download the ATG software from https://edelivery.oracle.com/.  Since there isn’t official software for mac OSX, select the 64 bit linux variety.

2. Select the desired software to download.  Choose the UNIX variants.  This guide will walk you through the installation of ATG 10.0.3 with the ACC, ATG Web Server Extensions, Commerce Reference Store (only initial installation) and Service.

Setting Up Oracle Commerce on Mac OSX 1

3. After downloading everything desired, run the ATG10.0.3 installer first.  For anyone new to unix, type ‘./’ before an BIN file to execute it from the terminal.

4. Next, install the ACC and ATG Web Server Extensions.  They should be painless.

5. For the final two products – CommerceReferenceStore and Service, we need to do a little hack to get them working.  When the ATG 10 installer created the ATG directory, it failed at logging the proper values into $DYNAMO_HOME/installconfig/config.xml.  The following installers use this file, so it must be present and accurate.

Go into your $DYNAMO_HOME/installconfig/config.xml and paste this in (change the values as per your needs):

<?xml version="1.0" encoding="UTF-8"?><config xmlns="*"><install xmlns=""><product name="ATG Portal" version="10.0.3"><configure>false</configure> </product><product name="ATG Adaptive Scenario Engine" version="10.0.3"><configure>false</configure> </product><product name="ATG Business Commerce and Merchandising" version="10.0.3"><configure>false</configure> </product><product name="ATG Content Administration" version="10.0.3"><configure>false</configure> </product><product name="ATG Consumer Commerce and Mercahndising" version="10.0.3"><configure>false</configure> </product></install><systemEnv xmlns=""><platform>osx</platform><jBossListenPort>8080</jBossListenPort><docRoot>/Users/pgoetsch/ATG/ATG10.0.3/home/doc</docRoot><locale>en</locale><appServer>JBoss</appServer><jBossVersion>5.0.0</jBossVersion><jBossHome>/Users/pgoetsch/jboss/JBoss-eap-5.0.0GA/jboss-as</jBossHome><baseLevel>ATG10.0.3_60</baseLevel><ATGJRE>/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home/bin/java</ATGJRE><rmiPort>8860</rmiPort><rootDir>C:ATGATG10.0.3</rootDir></systemEnv></config>

6. With the new config.xml file in, we can now run the Service and CommerceReferenceStore installers without error.

7. ATG is now successfully installed on your mac! It will function the same as on a Windows PC.  Set your $DYNAMO_HOME and $DYNAMO_ROOT variables for the system.  From the command prompt:

sudo pico/etc/profile

Add the variables to the file.  You’ll need to log out and log back in for the changes to take effect.

export DYNAMO_ROOT=/Users/pgoetsch/ATG/ATG10.0.3export DYNAMO_HOME=$DYNAMO_ROOT/home

Adding Oracle into the Equation

The new ATG installation wouldn’t do much without a database.  With a mac, there are two realistic choices:

1. MySQL – not recommended because it’s very buggy.  You’ll also have to forever convert any DDL files you’ve made into Oracle syntax because there are almost no ATG developers that use MySQL.

2. Oracle – this is the preferred database for ATG development for many reasons.  Most ATG applications use Oracle anyway, so why not develop in it to begin with?  The rest of this guide will detail how to set up an oracle database on a mac.

There aren’t any Oracle releases compatible with ATG and a mac computer.  There is one Oracle database available for mac computers, however it will not work with ATG.  The only alternative is to run a virtual machine with Oracle installed.  Then with some easy port forwarding, applications will be able to flawlessly use the database running on the VM.

Setting up the virtual machine is very easy.  Here’s how:

1. Download and install Virtualbox for mac from here;

2. If you’re a sysadmin and can handle installing and configuring Oracle on a linux image, then download an image and go.  Alternatively, Oracle has released an image running Oracle Linux 5 with Oracle already installed and configured.  The image can be downloaded from here.

3. Import the image into virtualbox.  Boot it and login with oracle/oracle:

Setting Up Oracle Commerce on Mac OSX 2

4. Verify the Oracle database by keying ‘sqlplus’ into the terminal.  A screen similar to this should appear:

Setting Up Oracle Commerce on Mac OSX 3

5. Now that the virtual machine is working, we need to setup some port forwarding so that we can reach it from the ‘outside’.  From the main virtualbox menu on the top of the screen, navigate to ‘Devices > Network Adapters…”.  Ensure that the networking type is NAT, and click the ‘Port Forwarding’ button.  Add the porting as follows:

Setting Up Oracle Commerce on Mac OSX 4

First we’re forwarding the port Oracle listens on (port 1521) to your mac’s own port 1521. Next, we’ve forwarded the default ssh port (port 22) to port 2222 on your mac.

6. After configuring port forwarding, the virtual machine can be shut down.  Starting the VM with the graphical desktop only to use the database is a waste of CPU.  To get around this, we can start the VM ‘headless’ and the entire GUI won’t come up.  To do this, add two aliases to your profile.

From the terminal:

sudo pico/etc/profile

Then, add the two aliases:

 alias startym="vboxmanage startym 'Oracle Developer Days_1' --type headless"

After adding the aliases and resetting the profile, the virtual machine can be started and stopped by just typing ‘startvm’ or ‘stopvm’ into the terminal.

Setting Up Oracle Commerce on Mac OSX 5

7. To communicate with the database to make new tables etc., we can simply SSH in with the port forwarding we set up.

Setting Up Oracle Commerce on Mac OSX 6

After doing these configurations for the virtual machine, you’ll have a fully functional ATG development environment.  There are two big benefits to running Oracle in a virtual machine.  First, the virtual machine is portable, so it’ll work on any computer that can support virtualbox.  Second, the VM can be shut down at the end of the day, instead of sucking your CPU even when it’s not being used.


  1. Frank 9 years ago

    This is been really helpful in getting an environment set up on my Mac. A few caveats, however.

    1. Oracle_developer_days.ova must be downloaded via Internet Explorer, or at least that’s what I found. Download manager, wget, straight safari download, etc. didn’t work.

    2. For the aliases, add them to ~/.bash_profile and they are:
    alias startodb=”vboxmanage startvm ‘Oracle Developer Days’ –type headless”
    alias stopodb=”vboxmanage controlvm ‘Oracle Developer Days’ poweroff”

    Also I added another alias:
    alias connectodb=’ssh -l oracle -p 2222 localhost’

  2. Chintan Desai 9 years ago

    Hello Peter,

    Thank you for posting these instructions. I wonder if steps have changed for new versions of ATG 10.x ?

  3. devon 9 years ago


    it should be the same I think… Let us know if you find any significant differences. Obviously if you’re using Endeca that’s a new part of the environment, but otherewise it should be pretty straightforward.


  4. Sdee 9 years ago

    Any suggestions on how to get this 10 .0.3 working with an IDE like eclipse? Don’t seem to find any plugins

  5. devon 9 years ago


    I don’t recommend the ATG Eclipse Plugin at all. I think it’s deprecated anyhow. Just use Eclipse, ant, some nice build tasks, and you should be good.

  6. Chintan Desai 9 years ago


    I am trying to install ACC9.1 on windows 7 that I am running using Parallels on my Mac. However, It would just quit saying cannot install with this configuration. Any idea why would it do that ? However, it would install just fine on a PC with Windows 7. Strange behavior

  7. Girish 9 years ago

    What is the workaround you suggest for using Search and Endeca?
    Something like install Endeca / Search on the same Virtual Box as oracle and use port forwarding to connect from local ATG/JBOSS?


  8. devon 9 years ago


    yes I think you’d have to run those within a VM and just connect to the VM’s IP:ports (not sure you’d need to forward any ports, just configure things up correctly).


  9. braghome 8 years ago

    For me only thing that worked after wasting some time was under ~/.bash_profile
    1. alias startodb=’VBoxManage startvm “Oracle Developer Days” –type headless’
    2. alias stopodb=’VBoxManage controlvm “Oracle Developer Days” poweroff’
    3. alias connectodb=’ssh -l system -p 2222 localhost’
    4. last is . .bash_profile
    I am on OS 10.9

  10. braghome 8 years ago

    the comment above does not show two hyphens on type.

  11. braghome 8 years ago

    sorry I put a typo ssh -l system should be
    ssh -l oracle

  12. Scott Stirling 8 years ago

    I set up with the latest/greatest VirtualBox and OS X using the Oracle VM. The only way I could get ssh to work from my laptop to the VM guest was using the command line like so (after installing VirtualBox and importing the OTN Developer Day VM):

    VBoxManage modifyvm ‘OTN Developer Day VM’ –natpf1 “guestssh,tcp,,2222,,22”

    For some reason using the GUI (exactly as shown above in screenshot) kept letting me connect to the VM via ssh but then it would time out after just hanging for a couple minutes.

  13. Scott Stirling 8 years ago

    Another change I had to make on the Oracle VM to get NAT port forwarding to work for tnslistener: add port 1521 to the trusted ports in the Firewall config, apply, then I could connect successfully. Until then, I could only connect on the NAT’ed port but it would timeout when trying to make an actual JDBC connection.

  14. raj 8 years ago

    Hi Peter Goetsch,

    Thanks for very nice post.

    I am just curious , is there any place i can download VM / virtual box with preinstalled ATG.
    i am looking for learning purpose.


  15. Peter Goetsch 8 years ago

    Hi Raj,

    As far as I know, you can’t get a VM anywhere with turn-key ATG installed. The closest you’ll get is using a vm pre-installed with oracle, then adding an application server, JDK, ATG libraries and finally search (search isn’t exactly required for just learning).

    I’d recommend using jboss as your application server since it has the easiest setup, then download the Commerce Reference Store package and using the CIM installer to get a storefront setup.

  16. Ralph Leonen 6 years ago

    Hi Peter,

    I’m able to get Weblogic up and running but when I run the OCPlatform11_2.bin file and follow the prompts for the ATG install I’m prompted to enter the full path to my Oracle_Home directory. When I enter my Oracle_Home path I get an error saying ‘invalid WebLogic install directory specified”. I’ve tried several permutations of my Oracle_Home and MW_HOME paths to no avail. Is this something you’ve encountered or do you know what could cause this issue? Any help would be greatly appreciated.


  17. C 5 years ago


    I am trying to set up weblogic on Mac OS X and running into issue with datasource. I can connect to DB with sqldeveloper but not able to connect through web logic.

    I am using localhost as hostname in sql developer and web logic data source.
    Any idea what may I be doing wrong?


Leave a reply

Your email address will not be published.