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.
VirtualBox is a free cross-platform virtualization app that makes it easy to simultaneously run multiple operating systems on your machine. In our usage it is merely a provider for Vagrant.
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://localhost:8081 or 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.
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 vagrant provision.
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.
A new 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
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.
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.
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 package.json file:
build: called when the site is started, for example to compile sass fileswatch: 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.
By default, vagrant-solidus will use Node version stable and npm version ^2.0.0. To use different versions, specify them in the package.json engines field.
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 thesassgem is installed - If the site has a
bower.jsonfile, thebowerpackages 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
solidusbin:./node_modules/.bin/solidus start --dev --loglevel=3 --port=PORT --livereloadport=PORT --logserverport=PORT
$ vagrant site stop
$ vagrant site restart
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 update command:
$ 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.
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 run command):
$ vagrant site run grunt my-site --option=something
$ vagrant site status
Run this command to follow the site's log:
$ vagrant site log
Warning: you will obviously lose your local site files!
$ vagrant site stop
$ cd ..
$ rm -rf my-site
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 Vagrantfile:
$ vagrant halt
$ vagrant plugin update vagrant-solidus
$ vagrant solidus-box init
$ vagrant up
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
Replacing 1.0.0.rc1 with the version number you want.
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.
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
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.
config.solidus.site_portsconfig.solidus.livereload_portsconfig.solidus.log_server_ports
It's also possible to remove ports reserved by older unused sites. The reserved ports are listed in this file: .vagrant-solidus/data/sites.json.