From 60b6996928a2d62e7fb91bd254c66df1b13f5b12 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Fri, 17 Sep 2021 00:01:11 +0200 Subject: [PATCH] Updated wiki --- Home.md | 66 +++++++++++++++++++---- Run-platypush-in-a-virtual-environment.md | 17 ++---- 2 files changed, 61 insertions(+), 22 deletions(-) diff --git a/Home.md b/Home.md index 81b9b10..0c63962 100644 --- a/Home.md +++ b/Home.md @@ -58,7 +58,52 @@ python setup.py build install ### Extra dependencies -There are two advised ways to install extra dependencies for the plugins you want to run. +There are four possible ways to install extra dependencies for the plugins and backend that you want to run on your +instance. + +#### `platyvenv` and `platydock` + +Upon installation, Platypush provides two utilities (`platyvenv` and `platydock`) that allow you to easily create +respectively a virtual environment or a Docker image for your Platypush application from a `config.yaml`. + +Write your `config.yaml` file, including all the plugins and backends that you want to enable. You can also include +external YAML files through the `include` directive (as long as they are in the same folder as your `config.yaml`), +and also custom Python scripts in the `scripts` directory. + +Make sure to define a `device_id` field in your `config.yaml`. It defines the name that `platyvenv`/`platydock` use to +identify and manage the service. + +##### Building the environment/image + +```shell +platyvenv build -c /path/to/your/config.yaml +# or +platydock build -c /path/to/your/config.yaml +``` + +##### Starting the environment/image + +```shell +platyvenv start +# or +platydock start +``` + +##### Stopping the environment/image + +```shell +platyvenv stop +# or +platydock stop +``` + +##### Removing the environment/image + +```shell +platyvenv rm +# or +platydock rm +``` #### `pip` extras @@ -70,22 +115,23 @@ pip install "platypush[http]" You can check the supported extras in the [`setup.py` file](https://github.com/BlackLight/platypush/blob/master/setup.py#L145). Installation of comma-separated lists of extras is also supported. -#### `requirements.txt` +#### Plugins/backends documentation -Alternatively, check [`requirements.txt`](https://github.com/BlackLight/platypush/blob/master/requirements.txt) for any extra dependencies you may want to install depending on your configuration. Uncomment the lines associated to the dependencies required by the integrations that you want to run and run: - -```shell -pip install -r requirements.txt -``` +The [official documentation](https://docs.platypush.tech) provides manual installation steps for all the supported +extensions. ### Configuration -Copy the [example `config.yaml`](https://github.com/BlackLight/platypush/blob/master/examples/conf/config.yaml) to `/etc/platypush/config.yaml` (global installation, discouraged) or `~/.config/platypush/config/config.yaml` (user installation, recommended). Explore it to get a grasp of the basic components of platypush and their configuration and change it according to your needs. -### Startup +Copy the [example `config.yaml`](https://github.com/BlackLight/platypush/blob/master/examples/conf/config.yaml) to +`/etc/platypush/config.yaml` (global installation, discouraged) or `~/.config/platypush/config/config.yaml` +(user installation, recommended). + +Explore it to get a grasp of the basic components of Platypush and their configuration and change it according to your needs. + +### Start up After configuring the server, start it by simply running `platypush`, `python -m platypush`. You can also a systemd service by copying the [example `platypush.service`](https://github.com/BlackLight/platypush/blob/master/examples/systemd/platypush.service) to either `/usr/lib/systemd/user/platypush.service` (global installation) or `~/.config/systemd/user/platypush.service` (user installation). **NOTE**: Platypush is only compatible with Python 3 and higher. After installing the application, you're ready to [start configuring it](quickstart) according to your needs. - diff --git a/Run-platypush-in-a-virtual-environment.md b/Run-platypush-in-a-virtual-environment.md index 9b6bf37..c0f7afa 100644 --- a/Run-platypush-in-a-virtual-environment.md +++ b/Run-platypush-in-a-virtual-environment.md @@ -5,7 +5,8 @@ You can run a Platypush instance in a [Python virtual environment](https://docs. * You can easily copy environments to other machines, as all the required dependencies and configuration for the application to run will all be inside of the `~/.local/share/platypush/` folder * 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. +The project comes with `platyvenv`, a script that should be installed in your bin path 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: @@ -17,12 +18,10 @@ device_id: my-device logging: - # Log to stdout/stderr, platyvenv will redirect the messages to - # ~/.local/share/platypush/venv//var/log level: INFO main.db: - engine: sqlite:////home/user/.local/share/platypush/venv//usr/share/db/platypush.db + engine: sqlite:////home/user/.local/share/platypush/venv/my-device/usr/share/db/platypush.db backend.pushbullet: token: YOUR_TOKEN @@ -73,6 +72,8 @@ Note that `platyvenv` will inspect your configuration file, automatically identi platyvenv start my-device ``` +The output of the Platypush service is printed on the terminal. + 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 @@ -81,13 +82,6 @@ curl -XPOST -H 'Content-Type: application/json' \ http://localhost:8008/execute | jq ``` -You can also easily inspect the application logs: - -```shell -cat ~/.local/share/platypush/venv//var/log/stdout.log -cat ~/.local/share/platypush/venv//var/log/stderr.log -``` - 6. Stop a running instance: ```shell @@ -99,4 +93,3 @@ platyvenv stop my-device ```shell platyvenv rm my-device ``` -