# 3- Manage vmr environment

## Clarification

A vmr environment consist of a directory and a template file call Vagrantfile.
A vmr object contains information to create and modify an vmr environment. Once the environment created and initialized the vmr object became optional and only the working directory and the Vagrantfile are the managers.

## Create a vmr environment

### Create a vmr object

    vmr_env <- vmrCreate(<boxname>)

vmrCreate() function create a vmr object using several arguments:
* name : the box name (from vmrList())
* provider: the provider name (from vmrList())
* version: (optional by default latest version is use)
* provider.options: specific provider options (vignette n°5)

### Load a vmr object

Set the working directory to a vmr environment who was already initialized.

    setwd("path/to/my/vmr/environment/")
    vmr_env <- vmrLoad()
    vmr_env

## Initialize a vmr environment

Initialize a vmr environment will create a Vagrantfile template into the working directory and download the box associated.

> The box download can be long depending of the box size and network bandwide. The box is save in vagrant environment (“~/.vagrant.d/”).

    vmr_env # created or loaded object
    # force.vagrantfile will override existing Vagrantfile template
    vmr_env <- vmrInitEnv(vmr_env, force.vagrantfile=TRUE)

### Clean a vmr environment

To remove any file created, boxes downloaded and provider instance run this commands:

    vmr_env <- vmrLoad()
    # provider cleaning
    vmrDestroy(vmr_env$id)
    # box cleaning
    vmrLocalBoxRemove(vmr_env$box, provider = vmr_env$provider, version = vmr_env$version)
    # remove the working directory

## Add options to vmr environment

Several functions need and can modify a vmr object to add options to the environment.
vmrInitEnv() have to be recall at vmr object modification.

### Upgrade environment

It’s possible to upgrade an environment to use the latest box version.

    vmr_env <- vmrUpdateEnvVersion(vmr_env)

### Shared files

To share a host directory to the guest.

    vmr_env <- vmrMountDir(vmr_env, src = "/" , dest = "/" )

## Manipulate a vmr environment

This functions manage the environment instance.
They have to be call in vmr environment (working directory), with no arguments.

    # Get environment status
    vmrStatus()
    # Start a provider instance
    vmrStart()
    # Save state and stop provider instance
    vmrSuspend()
    # Resume a saved provider instance
    vmrResume()
    # Stop a provider instance
    vmrStop()
    # Remove a provider instance
    vmrDestroy()

### Snapshot

Manage provider instance with snapshot.

    # Take a snapshot
    vmrTakeSnapshot("my snapshot")
    # resume a snapshot
    vmrRestoreSnapshot("my snapshot")
    # list snapshots
    vmrListSnapshot()

## Vignette summary

1. Working with vmr package
2. Start my first environment
3. Manage vmr environment
4. Manage boxes
5. Manage providers
6. Development with vmr
7. CI/CD
8. Functions resume

### Next vignette : 4-Manage Boxes