Nagrant: nodejs vagrant box made easy

Vagrant is a great tool to set up a development environment:

  • you can easily create an environment that resembles your production environment. No more time wasted to search why something work on localhost and not on production. As a bonus, some host providers can use your vagrant box to deploy your application (Amazon EC2, DigitalOcean, …)
  • any member of your team have the same environment, avoiding the long how to install section on the readme, explaining all the dependencies for your project.
  • it work on Windows.

Some preconfigured vagrant boxes exists for many languages and different software, but they are difficult to use or configure and can’t be a pain for new developers.

Laravel has a tool named Homestead to your make life easier : one single command and a preconfigured vagrant box is set up for your project. If you want to update the configuration, a single yaml file is available with explicit name for each options.

What is Nagrant

Nagrant is a small nodejs command utility like Homestead: it create everything you need to launch a preconfigured vagrant box and run your nodejs any application without intervention.

Configuration options can be modified from a single yaml file. And you can still customize it more with a script called at the end of the provisioning of the VagrantFile. Or even modify the VagrantFile to set up more customisation.

Nagrant don’t pollute your project with many files: only the required nagrant.yml and VagrantFile are added, and the if you ask Nagrant to create it.

Nagrant work on Linux, MacOS and Windows.

How to

To work, Nagrant required nodejs, npm and vagrant. It can be installed locally or globally. Having Nagrant installed locally unsure your team to have everything working without how to install section on your readme.

To init Nagrant, you just need to launch a terminal and type nagrant make and then, to launch your box, use vagrant up.



Nagrant can install MySQL, Redis or MongoDB only by setting the configuration flags to true in the configuration file and then launch vagrant provision. If you need to install more package or do some magic on your box, you can use the files and do anything you want. To generate the file, you can use nagran make --after.

Folder mapping

By default, Nagrant map the current directory to /home/vagrant/node inside the box. You can add more directories with the folders property.

- map: ./
to: /home/vagrant/node
- map: /home/USER/work/something
to: /home/vagrant/something

Nodejs instance

By default, Nagrant come with a yaml file who should be able to launch any project with a index.js file in the root directory. Everything is managed by the node property of the yaml file. You can even launch more node instance inside you box. And if you want to add environment variable to a nodejs instance, you can use the params object for your node app.

- dir: /hone/vagrant/node
script: index.js
- PORT: 8080
- MONGO_NAME: test
- dir: /hone/vagrant/node/background
script: cron.js

Auto restart is managed with nodemon and every change trigger a relaunch of the nodejs process.

Log will be redirected to a file named after your script file, like index-out.log.

Port forwarding

If you want to forward port to your host machine, you can use the ports property. By default, 80 is forwarded to 8080 and 443 to 4430. You can forward any port you like but be sure they are available on your host.

- from: 8080
to: 80
- from: 443
to: 44300