Vae Local Development Environment

The Vae Local Development Environment is a software package that you can install on your local computer. It allows you to preview pages that you are editing on your local machine. All VaeML tags are supported, and they will pull from the live data on your website.

The Vae Local Development Environment can run in two separate modes.

The original mode is implemented as a proxy server that transparently and quickly sends your local source code to the Vae servers to be processed. It does not actually perform rendering on your local machine, despite the fact that it may seem that way.

The newest mode (released in version 0.7.0) is a full stack renderer that runs on your local machine. In order to use full stack mode, you must have the latest versions of vae-remote, vae-thrift, and vaeql installed. On macOS, this can be accomplished through Homebrew. For Windows or Linux, you must compile and install from source by checking out the latest source from Github.

Installing

The Vae Local Development Environment is supported on all major desktop operating systems: Mac OS X, Windows, and UNIX/Linux. If you use another operating system, contact your account manager and we’ll try to get you up and running as well.

As of September 6, 2013, Vae Local is now distributed as a Ruby gem. This means that you must first install a working version of Ruby on your system. Instructions for installing Ruby are included under the following sections, depending on your OS.

Installing on macOS

Prerequisites: Installing on macOS is supported on all versions of Mac OS X from 10.4 (Tiger) through 10.11 (El Capitan).

Firstly, though, you need to have Xcode Developer Tools installed. Please make sure Xcode is installed before installing the Vae Local Development Environment. For help installing Xcode, I recommend following steps 1 and 2 of this tutorial.

If you wish to use the Full Stack mode, you also need to install VaeQL, Vae Thrift, and Vae Remote via Homebrew:

brew tap actionverb/tap
brew install vae-remote vae-thrift vaeql

To install Vae Local: Simply install the ‘vae’ Ruby gem. You can do that by typing the following at a command prompt:

gem install vae

Installing on Windows

Prerequisites: The Vae Local Development Environment for Windows is supported on Windows 2000, XP, Vista, and Windows 7.

You first need a working copy of Ruby with the Development Kit installed. The easiest way to do that on Windows is to install the RubyInstaller. Make sure to also download the Development Kit. Once that’s installed, you’re ready to install Vae Local.

If you wish to use the Full Stack mode, you also need to install VaeQL, Vae Thrift, and Vae Remote. Do that by following the instructions in each individual README here:

https://github.com/actionverb/vae_remote
https://github.com/actionverb/vae_thrift
https://github.com/actionverb/vaeql

To install Vae Local: Simply install the ‘vae’ Ruby gem. You can do that by typing the following at a command prompt. Note that if you used RubyInstaller, you may need to use its provided command prompt for running this command.

gem install vae

Installing on a UNIX/Linux system

Prerequisites: The Vae Local Development Environment for UNIX/Linux requires Ruby 1.8.5. You can check your Ruby version by typing ruby -v at the shell prompt. You should also have the Ruby Development Headers and a working compiler suite. If you do not have Ruby 1.8.5, use your distribution’s package manager to install the latest version of Ruby and the Development Headers.

If you wish to use the Full Stack mode, you also need to install VaeQL, Vae Thrift, and Vae Remote. Do that by following the instructions in each individual README here:

https://github.com/actionverb/vae_remote
https://github.com/actionverb/vae_thrift
https://github.com/actionverb/vaeql

To install: Simply install the ‘vae’ Ruby gem. You can do that by typing the following at a command prompt:

gem install vae

Usage

The Vae Local Development Environment is typically run from the command line, and usually in conjunction with the Vae Subversion service. To start the Vae Local Preview Server, simply open a Terminal, cd to the folder containing your website and then type one of the following commands:

For the proxy server mode:

vae

For local full stack mode:

vae --full-stack

If the current folder was checked out from the Vae Subversion service, Vae will be able to autodetect that it is a Vae site, the Vae site name (from the __vae.yml file in the folder) and your Vae username (from Subversion’s records). If not, you will need to specify these options on the command line, as described in the next section.

You will be prompted to enter your Vae password (the password for the Vae user that was used to check out the Subversion working copy). This is a security feature that prevents anyone from accessing your data without your permission.

Once the password has been approved, your local preview server will be running on http://localhost:9999/. You can open a browser window and use your website locally.

Command Line Arguments

The vae command accepts command line options in standard UNIX style. Here are the available options:

Usage: vae [options]
         starts a local development server
       vae [options] deploy
         promotes the source in Git/Subversion repository to the FTP
  If you are using the Vae Production environment features:
       vae [options] stage
         promotes the source in Git/Subversion repository to the staging environment
       vae [options] stagerelease
         promotes the source in Git/Subversion repository to the staging environment
         and releases it to the production environment
       vae [options] release
         releases the current staging environment to the production environment
       vae [options] rollback
         rolls back the production environment to a previous release
Available Options:
    -u, --username <username>        Your Vae username
    -p, --port <port number>         Start server on this port
    -r, --root <path to site root>   Path to the root of the local copy of your Vae site.
    -s, --site <subdomain>           Vae subdomain for this site
    -f, --full-stack                 Run in Full Stack Mode (experimental)
    -d, --data-path <path>           Where to Store Content and Image Data When In Full Stack Mode
    -l, --log-level <level>          Vaedb Log Level (for Full Stack Mode)
    -h, --help                       Show this help message

Deploying the Git/Subversion copy to your webspace

To deploy the version of your website as stored in Git or Subversion to your webspace, simply type vae deploy. You will have to enter your Vae password to complete this step. If you are using the Vae Production Environment, please see the section below for more detailed commands.

Make sure that you have checked in all local files before running this command. If you are using branches inside your Git or Subversion repository, make sure that you have properly set the active branch in the Site > Git/Svn/FTP tab.

You can also deploy from Git or Subversion to your webspace directly on the Site > Git/Svn/FTP tab.

Vae Production Environment

If you are using the Vae Production Environment, there are more options available to you. Type vae stage to deploy the website from Git/Subversion to the Staging Environment. Type vae release to release the Staging Environment to the Production Environment. Type vae stagerelease to deploy the website from Git/Subversion to the Staging Environment and Production Environment.

Known Limitations

There are a few known limitations with the Vae Local Development Environment. We are researching how to best solve these problems, but for now, here is a list of the currently known limitations:

In proxy mode, using require, require_once, include, or include_once in PHP files will include the copy of that file as hosted on the FTP, not the local copy. Use full stack mode to get around this limitation.

Alternatively, there are 2 other workarounds: 1. store functions in the __vae.php file, as this will be processed normally. 2. use the vae_include() function.
PayPal and PayPal Express Checkout flow cannot be tested locally because it requires the external PayPal servers to be able to connect inward.

« Previous: Next: »

Documentation and Integration Center

Vae Guide