From 314ab1b7059cd2e11534eea9fa38a2818e0f31b2 Mon Sep 17 00:00:00 2001
From: orrpan <orrpan@users.noreply.github.com>
Date: Wed, 6 Feb 2019 21:12:23 +0100
Subject: [PATCH] Venv documentation (#1033)

* Added guide for virtual environment

* grammer

* Update virtual_environment.md

* Update virtual_environment.md

* Update index.md
---
 docs/getting_started/running_zigbee2mqtt.md |   2 +-
 docs/index.md                               |   1 +
 docs/information/virtual_environment.md     | 116 ++++++++++++++++++++
 3 files changed, 118 insertions(+), 1 deletion(-)
 create mode 100644 docs/information/virtual_environment.md

diff --git a/docs/getting_started/running_zigbee2mqtt.md b/docs/getting_started/running_zigbee2mqtt.md
index fc571ee3..c970bfdf 100644
--- a/docs/getting_started/running_zigbee2mqtt.md
+++ b/docs/getting_started/running_zigbee2mqtt.md
@@ -1,7 +1,7 @@
 # Running Zigbee2mqtt
 These instructions explain how to run Zigbee2mqtt on bare-metal Linux.
 
-Other ways to run Zigbee2mqtt are [Docker](../information/docker.md) and the [Hass.io Zigbee2mqtt add-on](https://github.com/danielwelch/hassio-zigbee2mqtt).
+Other ways to run Zigbee2mqtt are [Docker](../information/docker.md), the [Hass.io Zigbee2mqtt add-on](https://github.com/danielwelch/hassio-zigbee2mqtt) and [Virtual Enviroment](../information/virtual_environment.md).
 
 For the sake of simplicity this guide assumes running on a Raspberry Pi 3 with Raspbian Stretch Lite, but will work on any Linux machine.
 
diff --git a/docs/index.md b/docs/index.md
index ddaa0176..c6509a46 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -43,3 +43,4 @@ Welcome to the Zigbee2mqtt documentation!
 * [3D cases](information/3d_cases.md)
 * [CC sniffer devices](information/cc_sniffer_devices.md)
 * [Alternative flashing methods](information/alternative_flashing_methods.md)
+* [Running Zigbee2mqtt in Virtual Environment](information/virtual_environment.md)
diff --git a/docs/information/virtual_environment.md b/docs/information/virtual_environment.md
new file mode 100644
index 00000000..508551b4
--- /dev/null
+++ b/docs/information/virtual_environment.md
@@ -0,0 +1,116 @@
+# Running Zigbee2mqtt in Virtual Environment
+It is possible to run Zigbee2mqtt in a virtual environment, this has been tested with a Raspberry Pi 3B+.
+
+This guide is similar to the [Running zigbee2mqtt guide](../information/running_zigbee2mqtt.md), follow the steps from there by replacing the steps with the ones from below.
+
+## 2. Installing
+```bash
+# Clone zigbee2mqtt repository
+sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
+sudo chown -R pi:pi /opt/zigbee2mqtt
+
+# Enter folder
+cd /opt/zigbee2mqtt
+
+# Install python env
+python3 -m venv .
+
+# Activate environment 
+source /opt/zigbee2mqtt/bin/activate
+
+# Upgrade pip, wheel and setuptools
+pip install --upgrade pip wheel setuptools
+
+# Install node environment
+pip install nodeenv
+
+# Init node environment
+nodeenv -p -n 10.15.1
+
+# Deactivate and activate environment to be sure
+deactivate
+source /opt/zigbee2mqtt/bin/activate
+
+# Install dependencies
+cd /opt/zigbee2mqtt
+npm install
+
+# Deactivate environment 
+deactivate
+```
+
+## 4. Starting zigbee2mqtt
+```bash
+# Enter folder
+cd /opt/zigbee2mqtt
+
+# Activate environment
+source /opt/zigbee2mqtt/bin/activate
+
+# Start
+npm start
+
+# ctrl + c to quit
+
+# Deactivate environment
+deactivate
+```
+
+## 5. (Optional) Running as a daemon with systemctl
+To run zigbee2mqtt as daemon (in background) and start it automatically on boot we will run Zigbee2mqtt with systemctl.
+```bash
+# Create a systemctl configuration file for zigbee2mqtt
+sudo nano /etc/systemd/system/zigbee2mqtt.service
+```
+
+Add the following to this file:
+
+```bash
+[Unit]
+Description=zigbee2mqtt
+After=network.target
+
+[Service]
+ExecStart=/bin/bash -c 'source /opt/zigbee2mqtt/bin/activate; /opt/zigbee2mqtt/bin/npm start'
+WorkingDirectory=/opt/zigbee2mqtt
+StandardOutput=inherit
+StandardError=inherit
+Restart=always
+User=pi
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Now continue with *Verify that the configuration works:* from the *Running Zigbee2mqtt guide*.
+
+## 6. (For later) Update Zigbee2mqtt to the latest version
+To update Zigbee2mqtt to the latest version, execute:
+
+```sh
+# Stop zigbee2mqtt and go to directory
+sudo systemctl stop zigbee2mqtt
+cd /opt/zigbee2mqtt
+
+# Activate environment 
+source /opt/zigbee2mqtt/bin/activate
+
+# Backup configuration
+cp -R data data-backup
+
+# Update
+git checkout HEAD -- npm-shrinkwrap.json
+git pull
+rm -rf node_modules
+npm install
+
+# Restore configuration
+cp -R data-backup/* data
+rm -rf data-backup
+
+# Deactivate environment
+deactivate
+
+# Start zigbee2mqtt
+sudo systemctl start zigbee2mqtt
+```