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 stable
- oldstable: previous Debian stable
- ubuntu: latest Ubuntu release
branch can be either:
- main: latest stable release
- dev: 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 ...