Using Vagrant Provision¶
To get familiar with application functionality or for the development purpose, you can provision Oro application using Vagrant.
Every Oro application has a Vagrantfile that allows you to set up a virtual machine with the running Oro application via a vagrant up command.
For example, to set up a VM with OroPlatform application locally, run:
git clone -b 2.6.14 https://github.com/oroinc/platform-application.git oroapp && cd oroapp vagrant up
After that in several minutes, you’ll get the running VM with Oro application that you can access on the URL http://localhost:8000/
The environment in the resulting VM and the provisioning steps automated via the vagrant file that replicates the process described in the Manual Installation Guide for the relevant application edition.
For more details on preparing the virtual platform for the virtual machine, please, see the Installation and Configuration section below.
Table of Contents
Installation and Configuration¶
- Windows, MacOS, Linux, or any other OS supported by Virtualbox and Vagrant
- 2048M available RAM on your PC
Start by installing the required software:
When you have installed VirtualBox, Vagrant, and Git, do the following:
Get the Oro application source code:
git clone -b 2.6.14 <oro_application_clone_url> oroapp && cd oroapp
Replace the <oro_application_clone_url> with the repository URL for the necessary Oro application:
OroCRM Community Edition https://github.com/oroinc/crm-application.git OroCRM Enterprise Edition https://github.com/oroinc/crm-enterprise-application.git OroPlatform https://github.com/oroinc/platform-application.git
The branch value (in this example 2.6.14) could be changed to another published release tag of the chosen Oro application, with the following constraints:
OroCRM Community Editions v.3.* and above branch value must be greather then 3.0.0-rc OroCRM Community Editions v.2.6.* branch value must be greather then 2.6.13 OroCRM Enterprise Editions v.3.* and above branch value should be greather then 3.0.0-rc OroCRM Enterprise Editions v.2.6.* branch value should be greather then 2.6.13 OroPlatform Community Editions v.3.* and above branch value must be greather then 3.0.0-rc OroPlatform Community Editions v.2.6.* branch value must be greather then 2.6.13
Previously published releases of the Oro Applications don’t have Vagrantfiles.
You can download and unpack the archive with Oro application source code instead of using Git repository. For more information, please, see Get the Oro Application Source Code.
Create and configure the virtual machine using Vagrant:
After the command execution is complete and the setup has finished, you can move on to using the Oro application. Login with credentials described in the Usage section.
When you run vagrant up for the first time, the Oro application installation may take some time, as the following time-consuming steps happen:
- Base CentOS/7 box download
- LEMP stack installation on the guest system
- Installation of composer dependencies for Oro application
- Oro application installation; note that demo data loading takes extra time.
The total time for the environment to get up and running depends on multiple factors, like your internet connection speed, CPU frequency, etc. Usually, it takes from 2 to 15 minutes.
Customize Installation Process¶
To customize default installation settings, modify the Provision configuration section of the Vagrantfile (please, refer to the commands and inline comments for more information).
The default values for the most important settings are:
DB_USER=dbuser DB_PASSWORD=DBP@ssword123 DB_NAME=oro
APP_HOST=localhost APP_USER=admin APP_PASSWORD=adminpass APP_LOAD_DEMO_DATA=y # y | n (whether to perform loading demo data during installation)
To customize the application hostname:
Set the new APP_HOST parameter value in the Vagrantfile (e.g. yourdomain.local), and
Map the new hostname to the application host IP address in your local hosts file, like in the following examples:
192.168.33.10 yourdomain.local www.yourdomain.local
Now you can open the Oro application in a browser by following the http://yourdomain.local/ URL.
Running Multiple Virtual Machines¶
To run multiple virtual machines simultaneously on a single host, ensure that every virtual instance uses a unique forwarded port. Before running an additional instance, modify its forwarded port in the host section of the config.vm.network “forwarded_port” setting in the Vagrant file. You can increment the value for every new virtual instance, e.g. instance A may have config.vm.network “forwarded_port”, guest: 80, host: 8000 configuration, and instance B may get config.vm.network “forwarded_port”, guest: 80, host: 8001.
Access the Installed Oro Application¶
After the VM setup has finished, you can access the application in your browser with the credentials defined by your installation configuration.
The default login details are:
- Application URL: http://localhost:8000/
- Admin Login: admin
- Admin Password: adminpass
If you have changed the application host, admin login, or password, please refer to the Vagrantfile for these details.
SSH Access to the Virtual Machine¶
To connect to the virtual machine via SSH, run the following command in the working directory on your host machine:
You will be logged in the virtual machine as vagrant user with sudo permission (you don’t need a password to use sudo command).
To configure SSH access to the virtual machine for the utilities that run on the host machine, like IDE, get the explicit SSH credentials by running the following command:
Access Oro Application Database¶
In the virtual machine, you can access the DB server using credentials provided in the Provision configuration section of the Vagrantfile. The default credentials are dbuser:DBP@ssword123.
To access the database from the host machine, configure and use the SSH connection to the guest machine database server as described in the section above.
- vagrant up – Creates and configures the virtual machine according to the vagrantfile. Unless the vagrant destroy has been launched, on the consecutive runs, vagrant up powers on the virtual machine. The provisioning script defined in config.vm.provision variable in the Vagrantfile is run only once.
- vagrant halt – Stops the virtual machine and saves the virtual machine image (without the current RAM state) to the host hard drive.
- vagrant suspend – Stops the virtual machine and saves the virtual machine image and the current RAM state the host hard drive.
- vagrant destroy – Destroys the VM and frees the resources of the host machine.
For more information, please see the official Vagrant documentation.