Updated wiki
parent
4ca8bceba2
commit
60b6996928
66
Home.md
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
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue