A neat starting point / development environment for Craft-based projects, with Vagrant configured and ready to go, Gulp set up to take care of things like rendering Sass, bundling Javascript, minifying CSS and images, and asset-syncing, Neat for elegant, semantic grid layouts, and a couple of shell scripts to simplify installing / restoring the database from backup.
- npm
- Gulp
- Vagrant
- Virtual Box
- rsync (optional, for asset-syncing)
Be sure to follow these steps carefully if you want Crafty Vagrant to behave!
-
Run the command
bash install.sh
- this will install and set up everything necessary (including Craft) in your project directory. If this is a fresh Craft install, answer 'y' to the prompt about replacing Craft's templates + config, otherwise - if this is an existing project - answer 'n'. -
If this is the first time you've used Crafty Vagrant, open your
hosts
file and add192.168.56.101 craft.local
(the hosts file is usually found at /etc/hosts
on OSX/Linux; %SystemRoot%\System32\drivers\etc\hosts
on Windows)
- Launch vagrant:
vagrant up
...and hopefully (after a short wait while your Vagrant machine is set up) you should be ready to go! The webserver should now be accessible from http://craft.local/
. If Craft backups are present in /app/craft/storage/backups
, the most recent one will automatically have been used to populate the database. Otherwise, you can install Craft by going to http://craft.local/admin/install
-
gulp watch
when you're ready to start developing: this will watch for changes to Sass, Javascript, or images, and perform appropriate tasks (compiling Sass, bundling javascript, etc) -
While
gulp watch
is running, any browser tabs with your dev site open in will update live (via the magic of Browsersync) as you edit styles, templates, etc. If you don't want live updating,gulp watch:tasks
will perform the same tasks (compiling Sass, etc) without the autorefresh. -
gulp watch
also generates a custom Modernizr build (atpublic/scripts/modernizr.js
) which only tests for features you're actually using in your styles and scripts (and which should therefore be a lot smaller and more performant than loading the whole Modernizr library). Note that this is not updated on every change of CSS or Javascript because that would slow things down too much, so if you add a new feature you'd like to detect you'll either need to stop and restartgulp watch
or, alternatively, rungulp modernizr
to update the build. -
Crafty has a database-provisioning shell script. If you run
gulp db:restore
, the most recent backup inapp\craft\storage\backups
will be restored. (Of course, you'll lose any current state of the database, so only do this when you're happy for that to happen) -
Crafty uses Browserify to keep Javascript modular. If you haven't used Browserify before, there's an example module in the /scripts directory.
-
If this is a fresh install of Craft, you may see error pages until you've installed it by visiting http://craft.local/admin/install
-
Crafty Vagrant will not install properly if the
unzip
command is not available from the command line. On Linux / OSX this is not usually a problem, but for Windows you might need to get an unzip executable file here and put it somewhere accessible from your PATH. -
Vagrant 1.8.7 (the current version at the time of writing) seems to have issues installing boxes on some machines. If
vagrant up
fails, try installing Vagrant 1.8.6 instead.
If you want to work on Crafty Vagrant itself (ie. on the default config / starting templates), three steps are required:
-
Run the install step with a
--dev
flag: eg.bash install.sh --dev
. This leaves copies of Crafty's default template / config files in the/src
folder (without the--dev
flag they are deleted from this directory as part of the install process, to avoid the potential confusion of having an unused templates directory kicking around) -
Add the line
define('CRAFT_TEMPLATES_PATH', "../src/craft/templates");
to the top of Craft'sapp/public/index.php
file. This lets you work directly on the source templates alongside a working installation of Craft. -
gitignore everything inside the
app
directory apart fromapp/src
to prevent it being checked into Crafty Vagrant itself. ie. add the following lines to.gitignore
:app/* !app/src*
- Ubuntu 16.04 (Xenial Xerus)
- Apache 2.4
- PHP 7 (with all Craft's required PHP extensions)
- Bourbon
- Neat
- jQuery
- Modernizr
If you're deploying to an Nginx server like Forge Laravel, you'll need to add the following lines to your server's Nginx config file.
See: https://github.com/nystudio107/nginx-craft/blob/master/forge-example/NginxConfiguration.conf for reference
location @enrewrites {
rewrite ^/en/(.*)$ /en/index.php?p=$1? last;
}
location /en/ {
try_files $uri $uri/ @enrewrites;
}
Crafty Vagrant's pattern library is adapted from Bitters © 2013–2014 thoughtbot, inc.
Crafty Vagrant's install script uses part of makeItCraft by Matt Stauffer.
Crafty Vagrant is also based on work by:
Copyright © 2014 Nice and Serious. Crafty Vagrant is free software, and may be redistributed under the terms specified in the license.