.. _create_new_instance:

Creating a new instance
=======================

A Vagrant instance can be a single machine or multiple machines.

.. image:: /images/quickstart/create_new_instance.png

Select a project
----------------

At all times, the vagrant instance will be bound to a project, for multiple reasons:

* Management purposes: Being able to list, sort all instances by project.
* Permissions control: Administrators can give or revoke permissions at the project level.
* If your project is linked to a git repository, your new instance will import those settings.

If don't have a project created yet, ask your administrator to create it for you.
Currently only administrators can add projects and link teams to it.

Select a host
-------------

Vagrant instances can be deployed on Virtualbox, but you might want to deploy your instance on Amazon or VMWare or any other provider.
This where Jeto shines the most. An administrator can add and configure any new *host* (also known as providers) from the Jeto administration UI.
Your *host* have two fields : the *provider name* and *parameters*.
Depending on your workflow, you might want to keep some variables at the project level and shared across all instances linked to the project ( Amazon Access Key, VMWare template name, etc.).

Select a host from the list, or ask your administrator to create one.

Name
----

Give your instance a sensible name. You have no restriction, aside from being not empty. It's only used for management purposes (listing, filtering the instances list, etc).

Environment
-----------

You can enter anything here. This variable is passed directly to your vagrant instance anytime a command is sent (up, halt, provision, destroy) and can be used to make run-time changes.
Most of the time we advise against it, but in some case you might not have the choice. Here a few examples:

* QA and DEV servers are not using the same mount folders.
* All emails sent from a QA servers should be sent to a catch-all inbox.
* PROD environment should never have DEBUG enabled at your application level.

You can test against this variable in your VagrantFile like this::

    if ENV['ENVIRONMENT'] != 'prod'
    end

In can also be invoked directly from your provision provider (Puppet, Chef, Ansible) or overwritten at the VagrantFile level.

Git
---

If your project is linked to a git repository, you will have the option to select your git reference.
Your reference can be a branch or a tag. We recommend only deploying a tag, but deploying a branch can have upsides.
Using a branch as your reference will let you **sync** the project without redeploying.
It can be very useful if you are deploying to a DEV environment or testing new providers and need quick re-deploy.

Download an archive
-------------------

Your other option to git is *download an archive*. The archive can be a zip or tar.gz archive.
The archive will be unpacked and a path will be auto-generated.