This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Configuration
Configuration file
You can use the default
config.yaml
as a template/reference.
The location of the config.yaml
to be used by the application is determined
in the following way:
- It can be passed through the command-line
-c
/--config
argument. - If not specified via
-c
, it will be read from thePLATYPUSH_CONFIG
environment variable. - If not specified, use
./config.yaml
if available. - If not available, and you are running Platypush within a Docker container,
or as a privileged user (and usually you shouldn't), or as a systemd service
created by a supported package manager, then
/etc/platypush/config.yaml
will be used if available. - Otherwise, if you are running Platypush as a non-privileged user or in a
virtual environment,
$XDG_CONFIG_HOME/platypush/config.yaml
will be used (defaults to~/.config/platypush/config.yaml
).
Scripts directory
By default, any custom Python scripts will be searched under
<CONFDIR>/scripts
, where <CONFDIR>
is the path to your config.yaml
.
You can override it in your config.yaml
:
scripts_dir: /path/to/custom/scripts
Since everything under the scripts directory will be imported as a submodule, you can create your own libraries of scripts that can import other scripts:
# Content of scripts/music.py
from platypush import run
def music_play(plugin='music.mopidy', resource=None):
run(f'{plugin}.play', resource)
# Content of scripts/lights.py
from platypush import run
def lights_toggle(plugin='light.hue', groups=('Living Room',)):
run(f'{plugin}.toggle', groups=groups)
# Content of scripts/home.py
from platypush import procedure
from scripts.music import music_play
from scripts.lights import lights_toggle
@procedure
def at_home():
music_play()
lights_toggle()
Splitting configuration on multiple files
The config.yaml
file can become very complex, especially if you embed many
hooks and procedures in it in YAML format.
To make the configuration more maintainable, and also to isolate modules that
you can reuse across multiple instances, you can leverage the include
directive:
# All paths are relative to config.yaml, or to the location of the current file
include:
- assistant.yaml
- db.yaml
- media.yaml
- mqtt.yaml
- sensors.yaml
# ...
Working directory
This is where the application will store its data and integration plugins will store their data. The order of precedence is:
-w
/--workdir
command line argument.- The
PLATYPUSH_WORKDIR
environment variable. - The
workdir
field in the configuration file. $XDG_DATA_HOME/platypush
(default:~/.local/share/platypush
) if launched with a non-privileged user,/var/lib/platypush
if launched as root or with a system user.
Database
The application stores entities, variables, users, integrations state and more on a database. The engine configuration supports the SQLAlchemy engine syntax.
Note: The application uses a local SQLite database by default, which is
natively supported by SQLAlchemy. The application has also been tested against
MySQL/MariaDB and Postgres, and should work fine with any modern relational
database supported by SQLAlchemy. However, any backend other than SQLite may
require an additional Python dependency for the SQLAlchemy driver (for example
pg8000
for PostgreSQL).
Order of precedence for the engine:
--main-db
/--db
command line argument.- The
PLATYPUSH_DB
environment variable. - The
main.db
field in the configuration file. sqlite:///<WORKDIR>/main.db
Device ID
The device ID is a unique identifier for a Platypush instance on a network and is used to reliably dispatch messages when multiple instances use a shared backend.
The order of precedence is:
--device-id
command line argument.- The
PLATYPUSH_DEVICE_ID
environment variable. - The
device_id
field in the configuration file. - The hostname of the machine.
systemd service
If you installed Platypush from a system package manager then you'll also have
a systemd
service installed for it.
You can start/enable Platypush like any other systemd
service:
# systemctl start platypush
# systemctl enable platypush
Or, if you want to run the Platypush service as a generic user:
❯ systemctl --user start platypush
❯ systemctl --user enable platypush
Otherwise, you can create your own systemd
service copying the provided
.service
file
to e.g. ~/.config/systemd/user
or /etc/systemd/system
.
Redis
Platypush uses Redis as a in-memory queue to deliver messages and as a pub/sub bus for inter-process communication.
If you installed Platypush through a package manager, then the Redis service will automatically be installed and started if you launch the Platypush service as a privileged user.
If you run Platypush in a container then by default it'll start its own Redis
instance through the --start-redis
command-line option.
You can customize the Redis configuration through the:
--redis-host
,--redis-port
and--redis-queue
command-line options.PLATYPUSH_REDIS_HOST
,PLATYPUSH_REDIS_PORT
andPLATYPUSH_REDIS_QUEUE
environment variables.- Through your
config.yaml
:
# See https://redis-py.readthedocs.io/en/latest/connections.html#redis.Redis
# for the full list of supported parameters
redis:
host: redis-host
port: 6379
username: redis-user
password: redis-pass
nginx
If you want to access your Platypush web panel outside your home network, it may be a good idea to use an nginx/Apache reverse proxy with a valid SSL certificate (e.g. managed by certbot). A sample an nginx configuration is provided in the repository.