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.
Installation
System package manager installation
Arch Linux
You can either install the
platypush
package (for the
latest stable version) or the
platypush-git
package
(for the latest git version) through your favourite AUR package manager. For
example, using yay
:
$ yay platypush
# Or
$ yay platypush-git
The Arch Linux packages on AUR are automatically updated upon new git commits or tags.
Debian/Ubuntu
- Add the Platypush APT key to your trusted keyring:
# wget -q -O \
/etc/apt/trusted.gpg.d/platypush.asc \
https://apt.platypush.tech/pubkey.txt
- Add the Platypush repository to your APT sources:
# wget -q -O \
/etc/apt/sources.list.d/platypush.list \
https://apt.platypush.tech/lists/platypush-<deb_version>-<branch>.list
Where:
-
deb_version
can be either:stable
: current Debian stableoldstable
: previous Debian stableubuntu
: latest Ubuntu release
-
branch
can be either:main
: latest stable releasedev
: a package always in sync with the latest git version
For example, to install the latest stable tags on Debian stable:
# wget -q -O \
/etc/apt/sources.list.d/platypush.list \
https://apt.platypush.tech/lists/platypush-stable-main.list
- Update your repos and install Platypush:
# apt update
# apt install platypush
Fedora
RPM builds targeting the latest Fedora release are automatically built on every push pipeline.
To install Platypush via RPM on Fedora:
- Add the Platypush RPM repository configuration to the package manager:
# yum config-manager --add-repo https://rpm.platypush.tech/platypush.repo
- Install Platypush, either the latest stable release or the rolling release updated on every commit to the main branch:
# yum install platypush
# Or
# yum install platypush-git
pip
$ pip install platypush
Or, for the latest git version:
# Official repo
$ pip install git+https://git.platypush.tech/platypush/platypush
# Github mirror
$ pip install git+https://github.com/blacklight/platypush
Docker
Base image installation
$ docker run -it --name platypush \
-p 8008:8008 \
-e "PLATYPUSH_DEVICE_ID=my-device" \
-v /path/to/your/platypush/config:/etc/platypush \
-v /path/to/your/platypush/share:/var/lib/platypush \
quay.io/platypush/platypush
The Web service will be available on http://localhost:8008
, and a default
configuration file will be initialized under
/path/to/your/platypush/config/config.yaml
if not available. The next
executions of the service can be triggered via docker start platypush
.
Note that this will install an Alpine-based image. For other base images (e.g. Debian, Ubuntu or Fedora) please consult the custom docker-compose way.
Also note that any extra plugin dependencies installed in the container will be lost if the container is removed.
In order to preserve the state of the container after installing and configuring
your plugins, you can leverage the docker commit
command:
❯ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f00546d3bd35 quay.io/platypush/platypush "/bin/sh -c 'platypu…" 38 minutes ago Up 8 minutes 0.0.0.0:8008->8008/tcp, :::8008->8008/tcp platypush
❯ docker commit f00546d3bd35 my-custom-platypush-image
sha256:13d4a4cae4e7eedee924a8a79deae9a9978aa70b46699c1f2abfd16bf5ed910b
# You can now use the my-custom-platypush-image even if the container is destroyed
Alternatively, you can use the platydock
command to directly create a Docker
image or a Dockerfile
from a configuration, with all the required plugins and
dependencies pre-installed.
The docker-compose way
$ git clone https://git.platypush.tech/platypush/platypush.git
$ cd platypush
# Copy .env.example to .env and edit docker-compose.yml if required.
# In particular, you may want /etc/platypush and /var/lib/platypush
# to point to directories on your hosts
$ docker compose up
Note that the default Dockerfile
uses Alpine, but in docker-compose.yml
you
can also specify an alternative Dockerfile
- Debian, Ubuntu and Fedora are
supported.
Exposing host devices
Note that some plugins may require access to the host hardware - such as USB devices, Bluetooth adapters etc.
In order to make these devices visible to the Docker container you may need to explicitly mount them as volumes.
For example, the serial
plugin may need to
access an Arduino/ESP device over USB. You can export only that device to the
Docker container:
$ docker run --device=/dev/ttyUSB0 ...
# Or, if you set up static naming via udev rules
$ docker run --device=/dev/arduino ...
Or, through docker-compose.yml
:
services:
platypush:
# ...
devices:
- /dev/ttyUSB0
Otherwise, for privileged access to the USB bus on a Linux host:
$ docker run --priviliged -v /dev/bus/usb:/dev/bus/usb ...
Or, through docker-compose.yml
:
services:
platypush:
# ...
volumes:
- /dev/bus/usb:/dev/bus/usb
Manual installation
$ git clone https://git.platypush.tech/platypush/platypush.git
$ cd platypush
$ pip install .