Vagrant plugin for Solidus sites development
This is a Vagrant plugin that adds a Solidus provisioner and command to manage Solidus sites. It enables you to easily create, run and update Solidus sites in the virtual machine without having to setup or log into the machine itself, through the vagrant command line interface.
Vagrant layers provisioning, file-based configuration, and a command-line interface on top of VirtualBox. This provides disposable, consistent environments for running development servers. Synced Folders and Networking features make the development experience the same as if running in your own environment: your own tools and whatever ports you’d like for access via your browser and other clients.
Install Pow (Mac only)
Among other things, Pow enables port proxying on your Mac, to let you route all web traffic on a particular hostname to another port on your computer. So you'll be able to access your site on
http://sitename.dev instead of
http://lvh.me:8081. No need to remember weird urls with changing port numbers! Install Anvil to get a handy menubar extra showing all of your Pow-powered hosts. This plugin will automatically configure Pow for your sites, if it is installed.
Create the Vagrant environment
Using this plugin, you can easily create a
Vagrantfile ready for Solidus:
$ vagrant plugin install vagrant-solidus $ mkdir solidus $ cd solidus $ vagrant solidus-box init
You are now ready to start the virtual machine:
$ vagrant up
This will boot the VM, and automatically install and configure everything that is required to run Solidus sites, a process called Provisioning:
Vagrantfile defines a pre-built 64-bit Ubuntu 12.04.3 LTS (Precise) “box” provided by the Vagrant team. This file also defines basic configuration such as port mapping and synced folder locations, it can be updated at any time. New boxes are only downloaded to your machine the first time you provision a new VM however. Once the operating system is booted, this plugin will perform additional provisioning. You can redo the provisioning process at any time by running
At this point, you are ready to work on your Solidus site!
A number of ports are automatically opened and forwarded to the virtual machine:
8081 to 8095 for the Solidus sites, and
35730 to 35744 for LiveReload. Whenever a site is started, two ports will be used for that site, so you can load them on your local browser.
site Vagrant command has been added to help create and manage your Solidus sites. To see all available sub-commands:
$ vagrant site
For help on a specific command, use the
-h argument. For example:
$ vagrant site create -h
Creating a site
The easiest way to create a new Solidus site is to use the handy Solidus site template. And the easiest way to do that is to use the following command:
$ vagrant site create my-site
This will create a new sub-directory called
my-site, initialized with a new site based on the latest Solidus site template. Another option is to create the directory and site yourself, from the ground up.
Adding an existing site
To work on an existing Solidus site, copy it or clone it to a sub-directory of this repo. The name of the site will be the name of that sub-directory.
Starting a site
Once the site has been added, start the Solidus server (which will run within the virtual machine) with this command:
$ cd my-site $ vagrant site start
You can now access the website on http://my-site.dev if you installed Pow. If not, look at the
start command's output, the site's urls will have been displayed. Note that many sites can run at the same time.
Hint: Site files are actually stored on your machine, not in the virtual machine. You can edit them as usual, and the server will load them from your machine. Stopping or deleting the virtual machine will not affect your files.
In order for a site to be started by this plugin, it only needs one thing: a
package.json file, with a dependency on Solidus. Two optional scripts can also be added to the
build: called when the site is started, for example to compile sass files
watch: called when the site is started, to automatically recompile the assets when they change
See the solidus-site-template's
package.json for an example.
Node and npm versions
By default, vagrant-solidus will use Node version
stable and npm version
^2.0.0. To use different versions, specify them in the
Site installation steps
When a site is started with
vagrant site start, the following steps are executed:
- If the site has a
Gemfilefile, the bundle is installed, else only the
sassgem is installed
- If the site has a
bowerpackages are installed
- The site's
npmpackages are installed
- The site's assets are compiled (see package.json):
npm --port=PORT --livereloadport=PORT --logserverport=PORT run build
- The site's assets are watched (see package.json):
npm --port=PORT --livereloadport=PORT --logserverport=PORT run watch
- The site is started, by calling the site's local
./node_modules/.bin/solidus start --dev --loglevel=3 --port=PORT --livereloadport=PORT --logserverport=PORT
Stopping a site
$ vagrant site stop
Restarting a site
$ vagrant site restart
Updating a site
As the Solidus and Solidus site templates projects progress, you'll probably want to update your sites to use the latest versions of those repos. This is done with the
$ vagrant site update
Note that this command will modify some of your site files. Make sure to review all changes applied to your files before committing those changes.
Running command line commands
If you need to run custom commands for your site, for example Grunt tasks, you will need to run them in the VM itself.
Hard way (ssh into the VM and run your commands):
$ vagrant ssh $ cd my-site $ grunt my-task --option=something $ exit
Easy way (use the
$ vagrant site run grunt my-site --option=something
Are my sites running?
$ vagrant site status
Debugging a site
Run this command to follow the site's log:
$ vagrant site log
Deleting a site
Warning: you will obviously lose your local site files!
$ vagrant site stop $ cd .. $ rm -rf my-site
Managing the VM
To stop the virtual machine, run:
$ vagrant halt
See the CLI docs for other commands.
To use the latest version of vagrant-solidus, simply update the plugin and re-initialize your
$ vagrant halt $ vagrant plugin update vagrant-solidus $ vagrant solidus-box init $ vagrant up
Installing a Specific Version
To use a specific version of vagrant-solidus, you can do the following;
$ vagrant halt $ vagrant plugin uninstall vagrant-solidus $ vagrant plugin install vagrant-solidus --plugin-version 1.0.0.rc1 $ vagrant solidus-box init $ vagrant up
1.0.0.rc1 with the version number you want.
Windows: 'ssh' executable not found
Vagrant needs an
ssh.exe executable to log into the virtual machine when running
vagrant ssh. Windows doesn't provide such an executable by default, but Git does. The easiest way to fix this problem is by adding Git's
bin path to the system's
PATH environment variable. In the Start menu, search for "system environment variables". Then locate the
PATH system environment variable, click
Edit and add Git's
bin path (probably located in
C:\Program Files (x86)\Git\bin). Note that you will need to restart your Command Prompt for the changes to take effect. Also, note that Git's own executables like
find.exe will be now be used instead of Windows' default executables.
Resetting the VM
If your virtual machine is in a weird state, the simplest solution is sometimes to rebuild it. All you need to do is destroy the VM and rebuild. This process will not delete your sites files, since they are hosted on your machine, not in the virtual machine.
$ vagrant destroy $ vagrant up
Adding or changing the forwarded ports
When a site is started, it requires 3 forwarded ports for the Solidus server, the log server and LiveReload. By default, 45 ports are forwarded when the box is started. Once a site has been started, its used ports will be reserved for later use. If you run out of ports, or if a default port is already used by another application on your machine, you can manage them directly in the Vagrantfile, with the following config variables, which should be arrays of available ports. Note that the box should be reloaded if those values are changed.
It's also possible to remove ports reserved by older unused sites. The reserved ports are listed in this file: