From 72711bc977c2c3063f912d2e63aff169cb7ba88f Mon Sep 17 00:00:00 2001
From: Fabio Manganiello <blacklight86@gmail.com>
Date: Tue, 18 Dec 2018 19:42:00 +0100
Subject: [PATCH] Added wiki docs for platydock

---
 Home.md                             |   1 +
 Running-platypush-in-a-container.md | 112 ++++++++++++++++++++++++++++
 2 files changed, 113 insertions(+)
 create mode 100644 Running-platypush-in-a-container.md

diff --git a/Home.md b/Home.md
index 487d3ea..c388821 100644
--- a/Home.md
+++ b/Home.md
@@ -6,6 +6,7 @@ Platypush
 * [Quickstart](quickstart)
 * [Plugins](plugins)
 * [Backends](backends)
+* [Run Platypush in a container](run-platypush-in-a-container)
 * [Shell interface](shell-interface)
 * [Writing your plugins](writing-your-own-plugins)
 * [Writing your backends](writing-your-own-backends)
diff --git a/Running-platypush-in-a-container.md b/Running-platypush-in-a-container.md
new file mode 100644
index 0000000..4dcaf05
--- /dev/null
+++ b/Running-platypush-in-a-container.md
@@ -0,0 +1,112 @@
+A very robust and scalable way to run Platypush is to build a Docker container image out of it.
+
+The project comes with `platydock`, that will be installed in your prefix upon Platypush installation. You can use it to build, remove, start, stop and list Platypush container images.
+Note that both `docker` 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:
+    # 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
+
+logging:
+    # Log to container stdout/stderr
+    level: INFO
+
+main.db:
+    engine: sqlite:////usr/local/share/platypush/platypush.db
+
+backend.pushbullet:
+    token: YOUR_TOKEN
+    device: platypush/your_device
+
+backend.redis:
+    # Redis and Platypush can't run in the same Docker container, but platydock will
+    # take care of pulling a Redis docker image and connect it to your container.
+    redis_args:
+        host: redis
+
+backend.mqtt:
+    host: YOUR_MQTT_HOST
+
+backend.tcp:
+    port: 3333
+
+backend.websocket:
+    port: 8765
+
+backend.http:
+    port: 8008
+
+redis:
+    host: redis
+
+tts.google:
+    language: en-US
+
+ifttt:
+    ifttt_key: YOUR_IFTTT_KEY
+
+autoremote:
+    devices:
+        OnePlus6:
+            key: KEY_1
+        PixelC:
+            key: KEY_2
+```
+
+2. Build a Docker image out of the configuration file using `platydock`:
+
+```shell
+platydock build my-image -c /path/to/config.yaml
+```
+
+Note that `platydock` will inspect your configuration file and automatically idenfify required dependencies and exposed ports.
+
+3. Start the new image:
+
+```shell
+platydock start my-image
+```
+
+4. After it's started up, if everything went smooth, you should already be able to send messages to the new container 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
+docker logs my-image
+```
+
+And you can also pass extra options to `platydock start`, that will be transparently passed to `docker run`, for instance `--add-host=`, `--device=` etc. Note that the exposed ports are automatically added to the container based on the configuration and by default will be exposed to the same port number on the host (e.g. 8008 on the container is published to 8008 on the host). You can override it through the `-p` option passed to `platypush start` (e.g. `-p 18008:8008` will map the port 8008 on the container to 18008 on the host).
+
+Also note that `platypush start` will start both your Platypush container and the support Redis container.
+
+5. Check the installed Platypush images:
+
+```shell
+platydock ls [filter]
+```
+
+6. Stop a running instance:
+
+```shell
+platydock stop my-image
+```
+
+7. Remove an image:
+
+```shell
+platydock rm my-image
+```
+