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
+```
+