obcommunity/open-balena-ui repository overview

⁠User Interface for Open Balena Admin

User interface for open-balena-admin⁠, an admin interface for open-balena.

⁠Dependencies

This project is dependent on open-balena-postgrest⁠ and open-balena-remote⁠, so the easiest way to get this up and running would be to install it via the open-balena-admin⁠ project.

⁠Configuration

There are a number of environment variables used to configure the ui:

• PORT - The port that the ui will listen on

• REACT_APP_OPEN_BALENA_POSTGREST_URL The URL (accessible to API) of the open-balena-postgrest instance, i.e. http://postgrest.openbalena.local:8000

• REACT_APP_OPEN_BALENA_REMOTE_URL The URL (accessible to API) of the open-balena-remote instance, i.e. http://remote.openbalena.local:10000

• REACT_APP_OPEN_BALENA_API_URL The URL (accessible to API) of the open-balena-api instance, i.e. https://api.openbalena.local

• REACT_APP_OPEN_BALENA_API_VERSION The version of open-balena-api that the above instance is running, i.e. v0.139.0

• REACT_APP_BANNER_IMAGE The URL of a custom banner image to use on the main dashboard.

⁠Exposing Device Connection Endpoints

Each device has a "Connect" button which uses balena image labels to discover available services on that device. To make use of this auto-discovery, you will need to add tags to each container within your balena application's docker-compose file where you would like to expose services. Examples of the three types of services available to expose are provided below (http, https and vnc); note that ssh services are enabled by default and do not need labels. When a device is running an application that exposes container services using the label constructs below, you will see the service appear in the list of available connections for that container when clicking the "Connect" button for that device in the admin ui.

HTTP Services:

    labels:
      openbalena.remote.http: '1'
      openbalena.remote.http.port: '5003'
      openbalena.remote.http.path: '/'

HTTPS Services:

    labels:
      openbalena.remote.https: '1'
      openbalena.remote.https.port: '1880'
      openbalena.remote.https.path: '/nr-admin'

VNC Services:

    labels:
      openbalena.remote.vnc: '1'
      openbalena.remote.vnc.port: '5900'

Note: The port specified above is a host container port, so the service needs to be mapped to a host port matching the port specified in the label in your docker-compose file.

⁠Dashboard URL Routes

open-balena-ui includes routes that conform to the standard balena convention that you will see when running balena devices using balena-cli. Specifically, if you point your browser to your open-balena-ui server with a path of /devices/<UUID>/summary, it will redirect you to the dashboard for that device. If you point the dashboard.yourdomain.com host to your open-balena-ui instance, the URL should conform to the standard balena convention.

⁠Compatibility

This project is compatible with open-balena-api v0.139.0 or newer, all the way up to the current builds (v0.190.0). See this project⁠ for a fork of bartversluijs' open-balena-helm project which has helm scripts to build a current version of open-balena.

⁠Installation

Set the required environment variables accordingly, and run yarn start from the main project folder. If running locally, you can access open-balena-ui via your web browser at http://localhost:PORT, and provided the configuration environment variables are appropriately pointed to live open-balena-api and open-balena-postgrest instances, you should be up and running.

⁠Development

For local development, be sure to set NODE_ENV to development and use npm run devserver to start the server with hot module replacement / reloading.

⁠Credits

• The ra-data-postgrest⁠ project was instrumental in establishing the link to the open-balena database