.. SPDX-License-Identifier: CC-BY-SA-4.0 Part 4: Components ------------------ Each :class:`~plinth.app.App` contains various :class:`~plinth.app.Component` components that each provide one small functionality needed by the app. Each of these components are instantiated and added to the app as children. Providing basic information about the app ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We need to provide some basic information about the application for the app to function normally. .. code-block:: python3 from plinth import app as app_module class TransmissionApp(app_module.App): ... def __init__(self): ... info = app_module.Info(app_id=self.app_id, version=1, name=_('Transmission'), icon_filename='transmission', short_description=_('BitTorrent Web Client'), description=description, manual_page='Transmission', clients=clients) self.add(info) The first argument is app_id that is same as the ID for the app. The version is the version number for this app that must be incremented whenever setup() method needs to be called again. name, icon_filename, short_description, description, manual_page and clients provide information that is shown on the app's main page. More information the parameters is available in :class:`~plinth.app.Info` class documentation. Managing a daemon ^^^^^^^^^^^^^^^^^ Transmission, like many services in the FreedomBox, requires a daemon to be running in the system to work. When the app is enabled, the daemon should be enabled. When the app is disabled, the daemon should be disabled. We should also show the status of whether the daemon is running in the app's view. All of these concerns are automatically handled by the framework if a :class:`~plinth.daemon.Daemon` component is added to the app. Let us do that in our app's class. .. code-block:: python3 from plinth.daemon import Daemon managed_services = ['transmission-daemon'] class TransmissionApp(app_module.App): ... def __init__(self): ... daemon = Daemon('daemon-transmission', managed_services[0], listen_ports=[(9091, 'tcp4')]) self.add(daemon) The first argument to instantiate the :class:`~plinth.daemon.Daemon` class is a unique ID. The second is the name of the `systemd `_ unit file which manages the daemon. The final argument is the list of ports that this daemon listens on. This information is used to check if the daemon is listening on the expected ports when the user requests diagnostic tests on the app. Managing web server configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Transmission provides a web interface to the user. This web interface needs to be proxied through a web server for security and access control. We will need to write a configuration snippet for Apache, the default web server on FreedomBox. This configuration snippet needs to be activated when our app is enabled. The configuration snippet needs to be deactivated when our app is disabled. All of these concerns are automatically handled by the framework if a :class:`~plinth.modules.apache.components.Webserver` component is added to the app. Let us do that in our app's class. .. code-block:: python3 from plinth.modules.apache.components import Webserver class TransmissionApp(app_module.App): ... def __init__(self): ... webserver = Webserver('webserver-transmission', 'transmission-plinth' urls=['https://{host}/transmission']) self.add(webserver) The first argument to instantiate the :class:`~plinth.modules.apache.components.Webserver` class is a unique ID. The second is the name of the Apache2 web server configuration snippet that contains the directives to proxy Transmission web interface via Apache2. We then need to create the configuration file itself in ``tranmission-freedombox.conf``. The final argument is the list of URLs that the app exposes to the users of the app. This information is used to check if the URLs are accessible as expected when the user requests diagnostic tests on the app. .. code-block:: apache ## On all sites, provide Transmission on a default path: /transmission ProxyPass http://localhost:9091/transmission Managing the firewall ^^^^^^^^^^^^^^^^^^^^^ FreedomBox has a tight firewall that closes off all TCP/UDP ports by default. If a service needs to available to users on a port, it needs to open the ports in firewalld, the default firewall configuration manager in FreedomBox. When the app is enabled, the ports need to opened and when the app is disabled, the ports needs to be closed. The FreedomBox framework again provides a component for handling these operations. In case of our app, there is no need to open a special port since the web ports are always kept open. However, it is still good to specify that we operate on http/https ports so that users can be provided this information along with additional information on whether the service is available over Internet. Create the :class:`~plinth.modules.firewall.components.Firewall` component during app initialization. .. code-block:: python3 from plinth.modules.firewall.components import Firewall class TransmissionApp(app_module.App): ... def __init__(self): ... firewall = Firewall('firewall-transmission', name, ports=['http', 'https'], is_external=True) self.add(firewall) The first parameter is a unique ID. Second one is the name of the app that as shown to the user in the firewall status page. Third argument is the list of services known to firewalld as listed in ``/usr/lib/firewalld/services/``. Custom services can also be written. The final argument decides whether the service should be made available by FreedomBox from external networks, essentially the Internet. User authentication and authorization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We wish that only users of FreedomBox should access the web interface of our app. Further, only users belonging to a specially created group are the only ones who should be able access the app. Again, FreedomBox handles all of this and we simply need to declare and use. First we need to register a user group with the FreedomBox framework in ``__init.py__``. .. code-block:: python3 from plinth.modules.users.components import UsersAndGroups class TransmissionApp(app_module.App): ... def __init__(self): ... groups = { 'bit-torrent': _('Download files using BitTorrent applications') } users_and_groups = UsersAndGroups('users-and-groups-transmission', groups=groups) self.add(users_and_groups) Then in the Apache configuration snippet, we can mandate that only users of this group (and, of course, admin users) should be allowed to access our app. In the file ``tranmission-freedombox.conf``, add the following. .. code-block:: apache ... Include includes/freedombox-single-sign-on.conf TKTAuthToken "admin" "bit-torrent" Showing a shortcut in the front page ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The app view we have created is only accessible by administrators of FreedomBox since only they can configure the app. Other users who have access to this app should have a way of discovering the app. This is done by providing a link in the front page of FreedomBox web interface. This is the page that user's see when they visit FreedomBox. To provide this shortcut, a :class:`~plinth.frontpage.Shortcut` component can added to the app. .. code-block:: python3 from plinth import frontpage group = ('bit-torrent', 'Download files using BitTorrent applications') class TransmissionApp(app_module.App): ... def __init__(self): ... shortcut = frontpage.Shortcut( 'shortcut-transmission', name, short_description=short_description, icon='transmission', url='/transmission', clients=clients, login_required=True, allowed_groups=[group[0]]) self.add(shortcut) The first parameter, as usual, is a unique ID. The next three parameters are basic information about the app similar to the menu item. The URL parameter specifies the URL that the user should be directed to when the shortcut is clicked. This is the web interface provided by our app. The next parameter provides a list of clients. This is useful for the FreedomBox mobile app when the information is used to suggest installing mobile apps. This is described in a later section of this tutorial. The next parameter specifies whether anonymous users who are not logged into FreedomBox should be shown this shortcut. The final parameter further restricts to which group of users this shortcut must be shown.