Updated wiki

Fabio Manganiello 2021-09-17 00:01:11 +02:00
parent 4ca8bceba2
commit 60b6996928
2 changed files with 61 additions and 22 deletions

66
Home.md

@ -58,7 +58,52 @@ python setup.py build install
### Extra dependencies ### 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 <device_id>
# or
platydock start <device_id>
```
##### Stopping the environment/image
```shell
platyvenv stop <device_id>
# or
platydock stop <device_id>
```
##### Removing the environment/image
```shell
platyvenv rm <device_id>
# or
platydock rm <device_id>
```
#### `pip` extras #### `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. 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: The [official documentation](https://docs.platypush.tech) provides manual installation steps for all the supported
extensions.
```shell
pip install -r requirements.txt
```
### Configuration ### 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). 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. **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. After installing the application, you're ready to [start configuring it](quickstart) according to your needs.

@ -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/<my-device>` folder * 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/<my-device>` 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. * 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. Note that both `python-venv` and `platypush` need to be installed on your host system for these steps to work.
Example: Example:
@ -17,12 +18,10 @@ device_id:
my-device my-device
logging: logging:
# Log to stdout/stderr, platyvenv will redirect the messages to
# ~/.local/share/platypush/venv/<my-device>/var/log
level: INFO level: INFO
main.db: main.db:
engine: sqlite:////home/user/.local/share/platypush/venv/<your_image>/usr/share/db/platypush.db engine: sqlite:////home/user/.local/share/platypush/venv/my-device/usr/share/db/platypush.db
backend.pushbullet: backend.pushbullet:
token: YOUR_TOKEN token: YOUR_TOKEN
@ -73,6 +72,8 @@ Note that `platyvenv` will inspect your configuration file, automatically identi
platyvenv start my-device 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: 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 ```shell
@ -81,13 +82,6 @@ curl -XPOST -H 'Content-Type: application/json' \
http://localhost:8008/execute | jq 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: 6. Stop a running instance:
```shell ```shell
@ -99,4 +93,3 @@ platyvenv stop my-device
```shell ```shell
platyvenv rm my-device platyvenv rm my-device
``` ```