From 80270f807cf544d54d7b70d80b9f3499f77643e0 Mon Sep 17 00:00:00 2001
From: Fabio Manganiello <blacklight86@gmail.com>
Date: Wed, 19 Dec 2018 23:09:22 +0100
Subject: [PATCH] Added documentation on platyvenv

---
 Home.md                                       |   1 +
 Running-platypush-in-a-container.md           |   6 +-
 Running-platypush-in-a-virtual-environment.md | 101 ++++++++++++++++++
 3 files changed, 105 insertions(+), 3 deletions(-)
 create mode 100644 Running-platypush-in-a-virtual-environment.md

diff --git a/Home.md b/Home.md
index c388821..128b7ea 100644
--- a/Home.md
+++ b/Home.md
@@ -6,6 +6,7 @@ Platypush
 * [Quickstart](quickstart)
 * [Plugins](plugins)
 * [Backends](backends)
+* [Run Platypush in a virtual environment](run-platypush-in-a-virtual-environment)
 * [Run Platypush in a container](run-platypush-in-a-container)
 * [Shell interface](shell-interface)
 * [Writing your plugins](writing-your-own-plugins)
diff --git a/Running-platypush-in-a-container.md b/Running-platypush-in-a-container.md
index 4dcaf05..e850d47 100644
--- a/Running-platypush-in-a-container.md
+++ b/Running-platypush-in-a-container.md
@@ -12,7 +12,7 @@ device_id:
     # NOTE: It's mandatory to specify a device_id when building
     # a Platypush container. Containers will have their hostname
     # dynamycally set by Docker and therefore won't be a reliable default
-    leibniz
+    my-image
 
 logging:
     # Log to container stdout/stderr
@@ -63,10 +63,10 @@ autoremote:
 2. Build a Docker image out of the configuration file using `platydock`:
 
 ```shell
-platydock build my-image -c /path/to/config.yaml
+platydock build -c /path/to/config.yaml
 ```
 
-Note that `platydock` will inspect your configuration file and automatically idenfify required dependencies and exposed ports.
+Note that `platydock` will inspect your configuration file and automatically identify required dependencies and exposed ports.
 
 3. Start the new image:
 
diff --git a/Running-platypush-in-a-virtual-environment.md b/Running-platypush-in-a-virtual-environment.md
new file mode 100644
index 0000000..95b198b
--- /dev/null
+++ b/Running-platypush-in-a-virtual-environment.md
@@ -0,0 +1,101 @@
+You can run a Platypush instance in a [Python virtual environment](https://docs.python-guide.org/dev/virtualenvs/). There are several advantages for this option:
+
+* You won't have to install dependencies at system level and you can easily create instances in user space
+* The available tools will take care for the required dependencies depending on your configuration. Just write your `config.yaml` and Platypush will figure out which dependencies are required by the plugins you wish to use
+* You can create multiple instances on the same machine and easily start, stop and remove them. Note however that this option will use more disk space compared to a system installation if you decide to use virtual environments: each environment will install its own set of dependencies instead of relying on those available on the system.
+
+The project comes with `platyvenv`, that will be installed in your prefix upon Platypush installation. You can use it to build, remove, start, stop and list Platypush virtual environments.
+Note that both `python-venv` and `platypush` need to be installed on your host system for these steps to work.
+
+Example:
+
+1. Create your own `config.yaml` file for a Platypush instance:
+
+```yaml
+device_id:
+    my-device
+
+logging:
+    # Log to stdout/stderr, platyvenv will redirect the messages to
+    # ~/.local/share/platypush/venv/<my-device>/var/log
+    level: INFO
+
+main.db:
+    engine: sqlite:////home/user/.local/share/platypush/venv/<your_image>/usr/share/db/platypush.db
+
+backend.pushbullet:
+    token: YOUR_TOKEN
+    device: platypush/your_device
+
+backend.redis:
+    redis_args:
+        host: localhost
+        port: 6397
+
+backend.mqtt:
+    host: YOUR_MQTT_HOST
+
+backend.tcp:
+    port: 3333
+
+backend.websocket:
+    port: 8765
+
+backend.http:
+    port: 8008
+
+tts.google:
+    language: en-US
+
+ifttt:
+    ifttt_key: YOUR_IFTTT_KEY
+
+autoremote:
+    devices:
+        OnePlus6:
+            key: KEY_1
+        PixelC:
+            key: KEY_2
+```
+
+2. Build a virtual environment out of the configuration file using `platyvenv`:
+
+```shell
+platyvenv build -c /path/to/config.yaml
+```
+
+Note that `platyvenv` will inspect your configuration file, automatically identify the required dependencies and install them in your virtual environment.
+
+3. Start the new environment:
+
+```shell
+platyvenv start my-device
+```
+
+4. After it's started up, if everything went smooth, you should already be able to send messages to the new environment over the available exposed service. For example, over JSON-RPC:
+
+```shell
+curl -XPOST -H 'Content-Type: application/json' \
+    -d '{"type":"request", "action":"shell.exec", "args": {"cmd":"hostname"}}' \
+    http://localhost:8008/execute | jq
+```
+
+You can also easily inspect the application logs:
+
+```shell
+cat ~/.local/share/platypush/venv/<my-device>/var/log/stdout.log
+cat ~/.local/share/platypush/venv/<my-device>/var/log/stderr.log
+```
+
+6. Stop a running instance:
+
+```shell
+platydock stop my-device
+```
+
+7. Remove an environment:
+
+```shell
+platydock rm my-device
+```
+