Update Vagrant documentation (#2163)

This commit is contained in:
Alexander Fortin 2017-03-08 12:49:32 +01:00 committed by Fredrik Lindqvist
parent 5e09baa1aa
commit a8d4d74c8c

View File

@ -10,7 +10,7 @@ footer: true
redirect_from: /getting-started/installation-vagrant/ redirect_from: /getting-started/installation-vagrant/
--- ---
A `Vagrantfile` is available into `virtualization/vagrant` folder for quickly spinning up a Linux virtual machine running Home Assistant. This can be beneficial for those who want to experiment with Home Assistant and/or developers willing to easily test local changes and run test suite against them. A `Vagrantfile` is available into `virtualization/vagrant` folder for quickly spinning up a Linux virtual machine running Home Assistant. This can be beneficial for those who want to experiment with Home Assistant and/or developers willing to easily test local changes and run test suite against them. In the same `virtualization/vagrant` folder there's also a `provision.sh` shell script which provides an easy way to interact with the Home Assistant instance running within the Vagrant VM.
<p class='note'> <p class='note'>
Vagrant is intended for testing/development only. It is NOT recommended for permanent installations. Vagrant is intended for testing/development only. It is NOT recommended for permanent installations.
@ -18,7 +18,7 @@ Vagrant is intended for testing/development only. It is NOT recommended for perm
## {% linkable_title Install Vagrant %} ## {% linkable_title Install Vagrant %}
You must have [Vagrant](https://www.vagrantup.com/downloads.html) and [Virtualbox](https://www.virtualbox.org/wiki/Downloads) installed on your workstation. You must have [Vagrant](https://www.vagrantup.com/downloads.html) and [Virtualbox](https://www.virtualbox.org/wiki/Downloads) installed on your workstation. Vagrant and Virtualbox support all the main platforms, including Windows, MacOS and Linux.
## {% linkable_title Get Home Assistant source code %} ## {% linkable_title Get Home Assistant source code %}
@ -44,46 +44,57 @@ $ git config --global core.autocrlf input
## {% linkable_title Create the Vagrant VM and start Home Assistant %} ## {% linkable_title Create the Vagrant VM and start Home Assistant %}
```bash ```bash
$ vagrant up $ ./provision.sh setup
``` ```
This will download and start a virtual machine using Virtualbox, which will internally setup the development environment necessary to start Home Assistant process and run test suite as well. After the VM has started successfully, the Home Assistant frontend will be accessible locally from your browser at [http://localhost:8123](http://localhost:8123) This will download and start a virtual machine using Virtualbox, which will internally setup the development environment necessary to start Home Assistant. The whole process might take up to 30 minutes to complete, depending on Internet connection speed and workstation resources. After the VM has started successfully, the Home Assistant frontend will be accessible locally from your browser at [http://localhost:8123](http://localhost:8123)
## {% linkable_title Stopping Vagrant %} ## {% linkable_title Stopping Vagrant %}
To shutdown the Vagrant host: To shutdown the Vagrant host:
```bash ```bash
$ vagrant halt $ ./provision.sh stop
``` ```
To start it again, just run `vagrant up` To start it again:
```bash
$ ./provision.sh start
```
## {% linkable_title Restarting Home Assistant process to test changes %} ## {% linkable_title Restarting Home Assistant process to test changes %}
The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Configuration section](/docs/configuration/) in the docmentation for more information about how to configure Home Assistant). The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Configuration section](/docs/configuration/) in the docmentation for more information about how to configure Home Assistant).
Any changes made to the local directory on your workstation will be available from the Vagrant host, so to apply your changes to the Home Assistant process, just restart it: Any changes made to the local directory on your workstation will be available from the Vagrant host, so to apply your changes to the Home Assistant process, just restart it using the provided `provision.sh` wrapper script:
```bash ```bash
$ touch restart ; vagrant provision $ ./provision.sh restart
``` ```
<p class='note'>
This command will only restart the Home Assistant process inside the Vagrant VM, it will not reboot the virtual machine. If that's what you want, the right command is <code>vagrant reload</code>
</p>
## {% linkable_title Run test suite (Tox) %} ## {% linkable_title Run test suite (Tox) %}
To run tests against your changes: To run tests against the local version of Home Assistant code:
```bash ```bash
$ touch run_tests ; vagrant provision $ ./provision.sh tests
``` ```
## {% linkable_title Cleanup %} ## {% linkable_title Cleanup %}
To completely remove the VM: To completely remove the VM
```bash ```bash
$ rm setup_done ; vagrant destroy -f $ ./provision.sh destroy
``` ```
You can now recreate a completely new Vagrant host with `vagrant up` To completely remove the VM **and** setup a fresh new environment:
```bash
$ ./provision.sh recreate
```