Self-Hosting your RetailPlayer Portal Instance - Technical Requirements

This document describes technical requirements for customers who wish to self-host their own RetailPlayer Portal instance.

Host Machine

• Machine running Ubuntu 24.04 LTS with the following minimum requirements:
  (the web application performances vary based on these requirements, make sure to monitor and adjust based on actual needs):

  • CPU: min. 4 cores

  • RAM: min. 8GB

  • Storage: min. 16GB - this highly depends on the number of audio files that will be uploaded (failover tracks and messages).
    Note: the installation script will check that at least 4GB are free and available before proceeding.

  • Network: Gigabit Ethernet or better

Domain Names

• The machine MUST be assigned 2 domain names:

  • one for the web access by users (E.g. xyz.customer.com)

  • one for the remote control access (i.e. remote-control.xyz.customer.com) - this is the one used by QR Code links to allow remote control of devices and access to the remote control API

• It is customer’s responsibility to register the domain names to be used for the RetailPlayer Portal at the chosen DNS registrar

Packages Required

• "docker" version 28.0.2 and “docker compose” version 2.34.0 must be installed in the system before proceeding with the RPP installation

• User with sudoer privileges
  (you may need to add your user to the docker group (i.e. executing: sudo usermod -aG docker <USERNAME>))

Install Docker from apt repository.

https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository

• whiptail is the software used to display the Barix’s Terms and Conditions to be read and accepted at the Portal’s installation time.

Network

• The Barix RetailPlayer Portal application must be allowed to connect with the following online services to operate:

  • https://flexa-base.azurewebsites.net (always required when portal is running)

  • https://rpp-license1.barix.com and https://rpp-license2.barix.com (always required when portal is running)

  • https://flexa-lookup.barix.com (always required when portal is running)

  • https://release.barixupdate.com (required only during the installation process)

• The RetailPlayer Portal can only be reached via HTTPS

• It is not possible to use a different port other than 443 to reach the Portal

• Other network rules to consider:

  • During the first installation it is possible to have the configuration script generating TLS certificates using Certboot, the process is easy and fully automated, but it requires an open HTTP connection to the machine used only during the first setup, otherwise the process exits with an error. Alternatively it is possible to generate the certificates yourself on a different machine copy them on the target machine and provide the path where these are stored during the configuration process.

    • When using Certbot to generate the certificates those will automatically renew on a regular basis, to successfully renew the machine requires access to Let’s Encrypt certificate servers:

      • acme-v02.api.letsencrypt.org (the primary ACME API endpoint)

      • *.letsencrypt.org (for OCSP and other related services)

• Device ↔︎ Portal communication is achieved over web secure socket (wss), the connection is initiated via HTTPS from the device to the Portal’s endpoint wss://<PORTAL_DOMAIN>/be/api/v1/device/ and maintained over time until one of the 2 parties breaks it

• Remote Control QR Codes open a control page which also maintains a secure websocket connection with the endpoint wss://<REMOTE_CONTROL_DOMAIN>/remote-control

Outgoing Connections (Portal → Internet)

Incoming Connections (Internet/Devices → Portal)

Notes

• WSS (WebSocket Secure): Secure WebSocket connections that initiate over HTTPS on port 443

• Port 443 Only: The portal cannot use any port other than 443 for HTTPS/WSS connections

• Certbot HTTP: Port 80 inbound access is only needed during initial setup if using automated certificate generation with certbot

• Manual Certificates: If generating certificates manually on another machine, the HTTP port 80 inbound rule is not required

• Remote Control Domain: May be different from the main portal domain. See domain chapter in this document.

• Persistent Connections: WebSocket connections are long-lived and maintained until disconnected by either party

Security Considerations

• All production traffic uses encrypted connections (HTTPS/WSS)

• HTTP is only used during initial certificate setup process

• WebSocket connections upgrade from initial HTTPS handshake

RetailPlayer Devices Requirements

• RetailPlayer devices must be running at least FW v7.0.0 to be used with self hosted RetailPlayer Portals

Product Key File

• The product key file (typically namedrpp-backend.key) - provided by Barix at purchase, this must be copied on the machine where the portal runs inside an arbitrary location. I.e. your $HOME directory. (1x) product key can be used for one instance of the RetailPlayer Portal. If more instances are required the customer needs to purchase more product keys.
  Re-use of the same product key is forbidden and will result in the portal to stop working.

Flexa API KEY

• The partner’s Flexa API key. When subscribing to the self-hosted version of the Portal, the customer receives an email from support@barix.cloud with a link to set a password and register on partner.barix.cloud where the API Key will be available

Pre-requisites install script

The below script rpp-setup.sh takes care of installing all the above mentioned prerequisites (creates a “retailplayer” user with sudo privileges, installs docker, docker-compose etc) and test connectivity requirements with the required services. This effectively releases the hassles for the user to install and configure the above requirements.

The script must be “executable” (chmod +x rpp_setup.sh) and must run with sudopermissions.

READ HERE: If you use the below script make sure to change the password of the retailplayer user with one that fits your security requirements.

rpp_setup.sh