Skip to content

Home

Jump to bottom
Gil Moskowitz edited this page Jul 11, 2018 · 11 revisions

Welcome to the xtuple-vagrant wiki!

As mentioned in the xtuple-vagrant README, xTuple uses Vagrant to create virtual machines for a number of different purposes. The goal of this wiki is to clarify how to set up and start using each of the different virtual machines for its intended purpose.

Common Instructions

Install Vagrant

You need to install vagrant regardless of how you intend to use your virtual machine:

  • Download and install VirtualBox 5.1.x (we haven't tried 5.2.x yet; someone should)
    • do not open the VirtualBox application
    • do not create a virtual machine
  • Download and install Vagrant 1.9.5 (we haven't tried 2.1.1 yet; someone should)
    • do not use Linux package managers like apt-get and gem install, as they may install versions of Vagrant that are not compatible with the xTuple virtual machine configurations
    • do not run vagrant yet

Now make sure your VMs will play nicely with your host machine:

host $ vagrant plugin install vagrant-vbguest

Install Git

You will need git on your host computer. The steps for installing it differ depending on your host operating system.

Getting Git on Linux

Typically this is a one-liner:

host $ sudo apt-get install git

Getting Git on Mac OS X

There are at least three ways to get Git for your Mac:

  • install Apple's Xcode from the App Store (it should be free)
  • install GitHub for Mac
  • build git from source

Getting Git on Windows

  • Download Git for Windows

  • Run the installer and "next" through the wizard until the step: "Adjusting your PATH environment."

    • Choose the third option, "Run Git and included Unix tools from the Windows Command prompt." This will allow the Windows command prompt to access both git and ssh commands.

    step-1

    • On the next step: "Configuring the line ending conversions", choose the second option: "Checkout as-is, commit Unix-style line endings".

    step-2

    • Choose "next" through any additional steps to complete the Git for Windows install.

    • Open the Windows Command Prompt as Administrator (Administrator access is required to create symlinks on Windows). The "Adjusting your PATH environment" step above will allow you to run git and unix commands in your Windows Command Prompt.

Check out the Source Code

Clone your forks of the xtuple and qt-client repositories to a directory on your host machine:

host $ mkdir dev
host $ cd dev
host $ git clone --recursive https://github.com/<your-github-username>/xtuple.git
host $ cd xtuple && git submodule update --init --recursive && cd ..
host $ git clone --recursive https://github.com/<your-github-username>/qt-client.git
host $ cd qt-client && git submodule update --init --recursive && cd ..

Set up Your VM

Clone xtuple's xtuple-vagrant repository in a separate directory adjacent to your development folder:

host $ cd ..
host $ ls dev       # this should show xtuple, qt-client, ...
host $ mkdir vagrant
host $ cd vagrant
host $ git clone https://github.com/xtuple/xtuple-vagrant.git   # no need to fork
host $ cd xtuple-vagrant

You might need to configure your VM before you start it for the first time. If you don't need this, go straight to the next step.

We've made it easy to change some basic settings that control how the VM interacts with the host computer and what software gets installed in the VM. You can change the amount of memory the VM uses, its hostname and IP address, what version of PostgreSQL is installed, etc.

There is a list of variables at the top of the Vagrantfile. You can override these settings by creating a file called xtlocal.rb and placing new variable assignments in this file. For example, if you need to change the amount of memory the VM can use, override the xtVboxMemory setting:

host $ cat 'xtVboxMemory = "2048"' > xtlocal.rb

One common case is configuring a second or third VM running on a single host. This is easy to do. You must override the network address of the VM and the network ports that the host forwards to the VM. To assign these ports manually, change the xtlocal.rb file to look like this:

xtHostAddr      = "192.168.33.11"
xtHostAppPort   = 8444
xtHostRestPort  = 3001
xtHostWebPort   = 8889

You can also use the xtHostOffset variable. First get the variables to change:

host $ egrep ^xtHost Vagrantfile > xtlocal.rb

Then edit the resulting file to look something like this:

xtHostOffset    = 2
xtHostAddr      = "192.168.33.12"
xtHostAppPort   = xtGuestAppPort  + xtHostOffset
xtHostRestPort  = xtGuestRestPort + xtHostOffset
xtHostWebPort   = xtGuestWebPort  + xtHostOffset

Important: Make sure the xtSourceDir variable matches the location of the cloned xTuple source code on the host machine. It should be a relative path

Important: The default configuration runs a script to set up the VM for mobile-web client development. You can override this by changing the xtHostSetupFile:

  • mvdev_setup.sh sets up the VM for developing the web API
  • qtsrc_setup.sh downloads the source code for Qt, then compiles and installs it. This takes a long time but is similar to the configuration we use to build the desktop client for releases. The resulting VM may be used for both desktop and web API development.
  • Create your own script to set up a VM for a different purpose.

Start and Connect to the VM

Start the virtual machine:

host $ vagrant up

Vagrant will automatically run the shell script named by the xtHostSetupFile variable in either the Vagrantfile or xtlocal.rb to install the right tools. This may take anywhere from a few minutes to a few hours to run, depending on which script you choose to run.

Connect to the virtual machine via ssh:

host $ vagrant ssh

Note that the xTuple source code is synced to the folder ~/dev:

vagrant $ ls dev    # you should see xtuple and qt-client

Start Developing

xTuple Web API

Start the datasource:

vagrant $ cd dev/xtuple/node-datasource
vagrant $ node main.js

Launch your local browser and navigate to application using localhost http://localhost:8888 or the static IP address of the the virtual machine http://192.168.33.10:8888. You will need to use a different IP address or port if you changed xtHostAddr or xtHostOffset in your xtlocal.rb.

The default username and password to your local application are admin

xTuple Desktop Client

The xTuple ERP desktop client application can use the database server running in the vagrant VM. Just make sure the application matches the xTuple database version - that is, run a 4.9.1 client to talk to a 4.9.1 database, 4.10.0 development client to talk to a 4.10.0 development database, etc. Log in to the database using the admin user, admin password (unless you changed it!-), and proper IP address and database server port.

You might find life easier if you set your PATH to include Qt. Edit ~/.bashrc and add a line like this at the end:

export PATH=/path/to/your/Qt-installation/bin:$PATH

Simplifying Desktop Development

If you set up the VM for desktop client development, you can tweak the VM configuration to make it easier to work in. Set the xtGui variable to true in xtlocal.rb and restart the VM:

host $ vagrant reload

This will reboot the VM and show the Linux display in a VirtualBox window so you can work in it directly. You can still connect to the VM on the command line with vagrant ssh. Remember that you should use vagrant commands to shutdown or reboot the VM whenever possible.

Using Qt Creator

Note: This section is optional and only relevant if you are changing the xTuple ERP desktop client application.

Qt Creator is a good IDE for working with Qt projects. The qtkpt_setup.sh and qtsrc_setup.sh scripts install Qt Creator for you but you do not have to use it. There are a few things you need to know:

  • Open the qt-client project by navigating to the qt-client directory and opening xtuple.pro
  • The xTuple widgets plugin must be installed properly before you can edit .ui files. Open a .ui within Creator and look for a section called xTuple Custom Widgets in the widgets palette.
  • If it isn't there, check Tools > Form Editor > About Qt Designer Plugins... and look under Failed Plugins.
    • If the xTuple plugin is listed but there was an error loading it, try clicking the Refresh button.
    • If the xTuple plugin is not listed:
      1. close the .ui file
      2. open any .cpp file in the widgets directory and make a simple change, like adding then removing a space
      3. save the modified .cpp
      4. click the Build Project button (looks like a hammer)
      5. open Refresh the plugins again as described above
      6. open a .ui file and double-check the widgets palette
    • If you continue to have problems:
      • make sure you have write-permissions on /usr/lib/x86_64-linux-gnu/qt5/plugins/designer and that it contains libxtuplewidgets.so
      • check that /etc/ld.so.conf.d/xtuple.conf exists and that it lists both the /home/vagrant/dev/qt-client/lib and /home/vagrant/dev/qt-client/openrpt/lib dirs. If not, create this file, add each of these directories on separate lines, and run ldconfig.

Additional Information

Shutting down, restarting, and destroying your VM:

Basic commands

See Configure Your VM if you have special needs, such as more than one xTuple vagrant VM. If running on a Mac with 8GB of RAM or less, set your VM to use 2GB. Set xtVboxMemory = "2048" in your xtlocal.rb, then either vagrant up or vagrant reload.

Clone this wiki locally