See hardware specific instructions on how to prepare your device at the Hardware section. Gather and read a lot of documentation on the web about first boot and flashing USB or SD Card on your hardware.

Recent images for supported targets are available here:

It is important to verify the images you have downloaded to ensure that the file has not be corrupted during the transmission and that it is indeed the image built by FreedomBox developers.

After the download you can use the image to boot supported hardware (including virtual machines). You'll need to copy the image to the memory card or USB stick as follows:

Tor Browser is the recommended way to browse the web using Tor. You can download the Tor Browser from https://www.torproject.org/projects/torbrowser.html and follow the instructions on that site to install and run it.

Tor Hidden Service provides a way to access your FreedomBox, even if it's behind a router or firewall.

To enable Tor Hidden Service, first navigate to the Anonymity Network (Tor) page. (If you don't see it, click on the FreedomBox logo at the top-left of the page, to go to the main Apps page.) On the Anonymity Network (Tor) page, under Configuration, check "Enable Tor Hidden Service", then press the Update setup button. Tor will be reconfigured and restarted.

After a while, the page will refresh and under Status, you will see a table listing the Hidden Service .onion address. Copy the entire address (ending in .onion) and paste it into the Tor Browser's address field, and you should be able to access your FreedomBox. (You may see a certificate warning because FreedomBox has a self-signed certificate.)

Currently only HTTP (port 80) and HTTPS (port 443) are accessible through the Tor Hidden Service configured on the FreedomBox.

FreedomBox provides a Tor SOCKS port that other applications can connect to, in order to route their traffic over the Tor network. This port is accessible on any interfaces configured in the internal firewall zone. To configure the application, set SOCKS Host to the internal network connection's IP address, and set the SOCKS Port to 9050.

XMPP is a federated protocol for Instant Messaging. This means that users who have accounts on one server, can talk to users that are on another server. However, for this to work, your FreedomBox needs to have a Domain Name that can be accessed over the public Internet. You can read more about obtaining a Domain Name in the Dynamic DNS section of this manual.

Once you have a Domain Name, you can tell your FreedomBox to use it by setting the Domain Name in the System Config.

Please note that Pagekite does not support the XMPP protocol at this time.

Currently, all users created through Plinth will be able to login to the XMPP server. You can add new users through the System Users and Groups module. It does not matter which Groups are selected for the new user.

There are two main mechanism to notify the Dynamic DNS server of your new IP address; using the GnuDIP protocol and using the Update URL mechanism.

If a service provided using update URL is not properly secured using HTTPS, your credentials may be visible to an adversary. Once an adversary gains your credentials, they will be able to replay your request your server and hijack your domain.

On the other hand, the GnuDIP protocol will only transport a salted MD5 value of your password, in a way that is secure against replay attacks.

This feature is implemented because the most popular Dynamic DNS providers are using Update URLs mechanism.

FreedomBox is bundled with a preset user account. This user also has superuser privileges via sudo. The default credentials are:

To login via SSH, to your FreedomBox:

$ ssh fbx@freedombox

Replace fbx with the name of the user you wish to login as. freedombox should be replaced with the hostname or IP address of you FreedomBox device as found in the Quick Start process.

fbx is the default user present on FreedomBox with superuser privileges. Any other user created using Plinth and belonging to the group admin will be able to login. The root account has no password set and will not be able to login. Access will be denied to all other users.

fbx and users in admin group will also be able to login on the terminal directly. Other users will be denied access.

If you repeatedly try to login as a user and fail, you will be blocked from logging in for some time. This is due to libpam-abl package that FreedomBox installs by default. To control this behavior consult libpam-abl documentation.

After logging in, if you want to become the superuser for performing administrative activities:

$ sudo su

Make a habit of logging in as root only when you need to. If you aren't logged in as root, you can't accidentally break everything.

To change the password of a user managed by Plinth, use the change password page. However, the fbx default user is not managed by Plinth and its password cannot be changed in the web interface.

To change password on the terminal, log in to your FreedomBox as the user whose password you want to change. Then, run the following command:

$ passwd

This will ask you for your current password before giving you the opportunity to set a new one.

You can create a wiki or blog to be hosted on your FreedomBox through the Wiki & Blog (Ikiwiki) page in Plinth. The first time you visit this page, it will ask to install packages required by Ikiwiki.

After the package install has completed, select the Create tab. You can select the type to be Wiki or Blog. Also type in a name for the wiki or blog, and the username and password for the wiki's/blog's admin account. Then click Update setup and you will see the wiki/blog added to your list. Note that each wiki/blog has its own admin account.

From the Wiki & Blog (Ikiwiki) page, select the Manage tab and you will see a list of your wikis and blogs. Click a name to navigate to that wiki or blog.

From here, if you click Edit or Preferences, you will be taken to a login page. To log in with the admin account that you created before, select the Other tab, enter the username and password, and click Login.

Besides the wiki/blog admin, other FreedomBox users can be given access to login and edit wikis and blogs. However, they will not have all the same permissions as the wiki admin. They can add or edit pages, but cannot change the wiki's configuration.

To add a wiki user, go to the Users and Groups page in Plinth (under System configuration, the gear icon at the top right corner of the page). Create or modify a user, and add them to the wiki group. (Users in the admin group will also have wiki access.)

To login as a FreedomBox user, go to the wiki/blog's login page and select the Other tab. Then click the "Login with HTTP auth" button. The browser will show a popup dialog where you can enter the username and password of the FreedomBox user.

Your FreedomBox contains the restore remoteStorage server, which means that it can serve as your personal backend for Unhosted apps. Make sure the package is installed in your Plinth.

Then create a remoteStorage account at https://<yourdomain>/restore/.

Warning: These user accounts are currently not integrated with Plinth user management, and public sign-up is enabled!

Once your FreedomBox is set up, and both PageKite and remoteStorage are running, try one of the following Unhosted apps (more are listed at http://unhosted.org/apps):

To connect the Unhosted app to your remoteStorage, click on the remoteStorage icon and type your address <user>@<yourdomain>, e.g.:

If this doesn't work, make sure that both PageKite and remoteStorage are running, and that your FreedomBox SSL certificate is trusted in your current browser session (important when using private browsing).

Finish the OAuth flow by authenticating with your password and authorizing access, then you should get redirected back to the Unhosted app, and you should be able to use it. All data of the Unhosted app is stored on your FreedomBox.

In a fresh image of FreedomBox, network is not configured at all. When the image is written to an SD card and the device boots, configuration is done. During first boot, FreedomBox setup package detects the networks interfaces and tries to automatically configure them so that FreedomBox is available for further configuration via the web interface from another machine without the need to connect a monitor. Automatic configuration also tries to make FreedomBox useful, out of the box, for the most important scenarios FreedomBox is used for.

There are two scenarios it handles: when is a single ethernet interface and when there are multiple ethernet interfaces.

Although the primary duty of FreedomBox is to provide decentralized services, it can't also act like a home router. Hence, in most cases, FreedomBox connects to the Internet and provides other machines in the network the ability to use that Internet connection. FreedomBox can do this in two ways: using a shared mode connection or using an internal connection.

When an interface is set in shared mode, you may connect your machine directly to it. This is either by plugging in an ethernet cable from this interface to your machine or by connecting to a Wi-Fi access point. This case is the simplest to use, as FreedomBox automatically provides your machine with the necessary network configuration. Your machine will automatically connect to FreedomBox provided network and will be able to connect to the Internet given that FreedomBox can itself connect to the Internet.

Sometimes the above setup may not be possible because the hardware device may have only one network interface or for other reasons. Even in this case, your machine can still connect to the Internet via FreedomBox. For this to work, make sure that the network interface that your machine is connecting to is in internal mode. Then, connect your machine to network in which FreedomBox is present. After this, in your machine's network configuration, set FreedomBox's IP address as the gateway. FreedomBox will then accept your network traffic from your machine and send it over to the Internet. This works because network interfaces in internal mode are configured to masquerade packets from local machines to the Internet and receive packets from Internet and forward them back to local machines.

The above default configuration may not be fit for your setup. You can customize the configuration to suit your needs from the Networks area in the 'setup' section of the FreedomBox web interface.

FreedomBox automatically configures networks by default and provides a simplified interface to customize the configuration to specific needs. In most cases, manual operation is not necessary. The following steps describe how to manually operate network configuration in the event that a user finds FreedomBox interface to insufficient for task at hand or to diagnose a problem that FreedomBox does not identify.

On the command line interface:

To see the list of available network devices:

nmcli device

To see the list of configured connections:

nmcli connection

To see the current status of a connection:

nmcli connection show '<conneciton_name>'

To see the current firewall zone assigned to a network interface:

nmcli connection show '<conneciton_name>' | grep zone

or

firewall-cmd --zone=internal --list=all
firewall-cmd --zone=external --list=all

To create a new network connection:

nmcli con add con-name "<connection_name>" ifname "<interface>" type ethernet
nmcli con modify "<connection_name>" connection.autoconnect TRUE
nmcli con modify "<connection_name>" connection.zone internal

To change the firewall zone for a connection:

nmcli con modify "<connection_name>" connection.zone "<internal|external>"

For more information on how to use nmcli command, see its man page. Also for a full list of configuration settings and type of connections accepted by Network Manager see:

https://developer.gnome.org/NetworkManager/stable/ref-settings.html

To see the current status of the firewall and manually operate it, see the Firewall section.

In the Plinth web interface, you can initiate a manual upgrade process from Upgrades page of the Settings section. Note that once the upgrades start, it may take a long time to complete and Plinth may seem to wait for the page to load.

Under some circumstances, automatic upgrades may fail and require you perform a manual upgrade action. Even upgrades initiated from Plinth may not finish properly. This may be because the upgrade process requires you to make a decision. In these cases, manual upgrade on the terminal may be the only option.

To perform manual upgrades on the terminal, login into FreedomBox on a terminal or using a remote secure shell (see Secure Shell section). Then run the following commands:

$ sudo su -
Password:
# apt-get update
# apt-get dist-upgrade

This will ask you if it is alright to install/upgrade (or remove) some packages and use (or release) some disk space. Say yes after review. In some cases, during the upgrades process you will be asked questions about modified configuration files, answering with a default Keep current configuration is usually safe.

Each interface is needs to be assigned to one (and only one) zone. Whatever rules are in effect for a zone, those rules start to apply for that interface. For example, if HTTP traffic is allowed in a particular zone, then web requests will be accepted on all the addresses configured for all the interfaces assigned to that zone.

There are primarily two firewall zones used. The internal zone is meant for services that are provided to all machines on the local network. This may include services such as streaming media and simple file sharing. The external zone is meant for services that are provided publicly on the Internet. This may include services such as blog, website, email web client etc.

For details on how network interfaces are configured by default, see the Networks section.

The following table attempts to document the ports, services and their default statuses in FreedomBox. If you find this page outdated, see the Plinth source for lib/freedombox/first-run.d/90_firewall and Firewall status page in Plinth UI.

See FirewallD documentation for more information on the basic concepts and comprehensive documentation.

service firewalld stop

systemctl stop firewalld

service firewalld start

systemctl start firewalld

firewall-cmd --zone=<zone> --list-services

firewall-cmd --zone=internal --list-services

firewall-cmd --zone=<zone> --list-ports

firewall-cmd --zone=internal --list-ports

firewall-cmd --zone=<zone> --remove-service=<service>
firewall-cmd --permanent --zone=<zone> --remove-service=<interface>

firewall-cmd --zone=internal --remove-service=xmpp-bosh
firewall-cmd --permanent --zone=internal --remove-service=xmpp-bosh

firewall-cmd --zone=internal --remove-port=<port>/<protocol>
firewall-cmd --permanent --zone=internal --remove-port=<port>/<protocol>

firewall-cmd --zone=internal --remove-service=5353/udp
firewall-cmd --permanent --zone=internal --remove-port=5353/udp

firewall-cmd --zone=<zone> --add-service=<service>
firewall-cmd --permanent --zone=<zone> --add-service=<interface>

firewall-cmd --zone=internal --add-service=xmpp-bosh
firewall-cmd --permanent --zone=internal --add-service=xmpp-bosh

firewall-cmd --zone=internal --add-port=<port>/<protocol>
firewall-cmd --permanent --zone=internal --add-port=<port>/<protocol>

firewall-cmd --zone=internal --add-service=5353/udp
firewall-cmd --permanent --zone=internal --add-port=5353/udp

firewall-cmd --list-all-zones

firewall-cmd --zone=<zone> --remove-interface=<interface>
firewall-cmd --permanent --zone=<zone> --remove-interface=<interface>

firewall-cmd --zone=external --remove-interface=eth0
firewall-cmd --permanent --zone=external --remove-interface=eth0

firewall-cmd --zone=<zone> --add-interface=<interface>
firewall-cmd --permanent --zone=<zone> --remove-interface=<interface>

firewall-cmd --zone=internal --add-interface=eth0
firewall-cmd --permanent --zone=internal --remove-interface=eth0

This hardware works but is not recommended due to freedom, performance-per-cost, or other concerns:

Note: As FreedomBox is in development state, Supported Hardware means that FreedomBox images are built for the said hardware and at least one developers has reported the basic functions to be working.

Although the project may focus on supporting specific devices, we are looking to support as wider a variety of hardware as possible that is suitable for FreedomBox needs. Take a look at the list of hardware targeted for support.

If you are a developer, consider adding hardware support for your device by modifying Freedom Maker and FreedomBox Setup.

FreedomBox Danube Edition is a custom casing around Cubietruck coupled with an SSD.

Cubietruck (Cubieboard3) is a single board computer with better performance than many other such boards. FreedomBox images are being built for it. For using this board as FreedomBox, a separate USB WiFi device that does not require non-free firmware is recommended.

FreedomBox SD card images for this hardware are being built. These SD card images are meant for use with the on-board SD card slot and won't work when used with a separate SD card reader connected via USB.

An alternative to downloading these images is to install Debian on Cubietruck and then install FreedomBox on it.

FreedomBox images for this hardware can be built using Freedom Maker.

FreedomBox Danue Edition

Cubietruck / Cubieboard3

FreedomBox SD card images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card and boot into FreedomBox.

Note: This image is for BeagleBone Black. It won't work on BeagleBone Green.

An alternative to downloading these images is to install Debian on BeagleBone and then install FreedomBox on it.

FreedomBox images for this hardware can be built using Freedom Maker.

None

The following similar hardware will also work well with FreedomBox.

FreedomBox SD card images for this hardware are being built. These SD card images are meant for use with the on-board SD card slot and won't work when used with a separate SD card reader connected via USB.

An alternative to downloading these images is to install Debian on the device and then install FreedomBox on it.

FreedomBox images for this hardware can be built using Freedom Maker once the support for it is added.

The following similar hardware will also work well with FreedomBox.

FreedomBox SD card images for this hardware are being built. These SD card images are meant for use with the on-board SD card slot and won't work when used with a separate SD card reader connected via USB.

An alternative to downloading these images is to install Debian on the device and then install FreedomBox on it.

FreedomBox images for this hardware can be built using Freedom Maker once the support for it is added.

Although untested, the following similar hardware is also likely to work well with FreedomBox.

FreedomBox disk images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card, USB disk, SSD or hard drive and boot into FreedomBox. Pick the image meant for all amd64 machines.

An alternative to downloading these images is to install Debian on the APU and then install FreedomBox on it.

The first network port, the left most one in the above picture, is configured by FreedomBox to be an upstream Internet link and the remaining 2 ports are configured for local computers to connect to.

FreedomBox images for this hardware, which is for all amd64 machines, can be built using Freedom Maker.

None

FreedomBox SD card images for this VirtualBox are available. Follow the instructions on the download page to download and verify VirtualBox images.

An alternative to downloading these images is to install Debian on VirtualBox and then install FreedomBox on it.

VirtualBox provides many types of networking options. Each has its advantages and disadvantages. For more information about how various networking types work in VirtualBox, see VirtualBox's networking documentation. https://www.virtualbox.org/manual/ch06.html

For a simple setup, it is recommended that you use a single network interface in your guest machine. This will make the first boot script automatically configure that interface as an internal network with automatic network configuration. Inside the guest machine, the networking is configured automatically and all the services are made available on this network interface. For more information on how networks are configured by default in FreedomBox, see Networks section.

What remains is to make those services available to the host machine or to other machines in the network. You must then choose one of the following types of networking for the network interface on your guest machine. To set a particular type of network for the guest's network adapter, go to the guest VM's settings then the network options and then select the adapter you wish to configure. There, set the network type from the available list of networks.

ssh -p 2222 fbx@localhost

Summary of various network types:

You can log in as the following user:

After logging in, you can become root with the command sudo su. See the FreedomBox usage page for more details.

If you wish to build your own images instead of downloading available images, it can be done using Freedom Maker.

FreedomBox SD card images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card and boot into FreedomBox. See also instructions for using an internal micro-SD with DreamPlug.

An alternative to downloading these images is to install Debian on DreamPlug and then install FreedomBox on it.

Note that the factory firmware configurations may vary between revisions of the hardware, and render some images incompatible. See the DreamPlug firmware page for information on what images are compatible and how to update your DreamPlug firmware.

FreedomBox images for this hardware can be built using Freedom Maker.

Instructions on how to test this hardware are available.

FreedomBox SD card images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card and boot into FreedomBox.

FreedomBox images for this hardware can be built using Freedom Maker.

FreedomBox SD card images for this hardware are available. Follow the instructions on the download page to create a FreedomBox SD card and boot into FreedomBox.

FreedomBox images for this hardware can be built using Freedom Maker.

The free firmware for these devices is not packaged in Debian yet. You can manually download and install the firmware as follows:

sudo su [enter password]
cd /lib/firmware
wget https://www.thinkpenguin.com/files/ath9k-htc/version-1.4-beta/htc_9271.fw
wget https://www.thinkpenguin.com/files/ath9k_firmware_free-version/htc_7010.fw

There are a number of incomplete projects that you might find useful, for setting up a wiki, an IM server, and so forth. To check these out, download the repository:

$ hg clone https://bitbucket.org/nickdaly/plugserver ~/plugserver

Then, read the README. It's pretty detailed. Also, if you can, it may be best to wait until these tools are fully integrated into the FreedomBox image. Otherwise, migrating from these custom tools to the officially supported FreedomBox tools may be difficult. Ultimately, that decision is up to you.

If you are a user experience designer, you can help FreedomBox with the following items:

FreedomBox is still under development any many components are yet to be worked on. You can contribute to the discussion on various technical design and implementation aspects of FreedomBox. See:

Plinth is a web interface built using Python3 and Django. FreedomBox applications are simply Django applications within the Plinth project. Hence, for the most part, writing a FreedomBox application is all about writing a Django application.

You should start by reading the Django tutorial. All the concepts described there are applicable for how plinth and its applications are be built.

We must first, of course, pick an application to add to FreedomBox. For the purpose of this tutorial, let us pick Tiny Tiny RSS. The project description reads as, Tiny Tiny RSS is an open source web-based news feed (RSS/Atom) reader and aggregator, designed to allow you to read news from any location, while feeling as close to a real desktop application as possible.

Majority of the effort in creating an application for FreedomBox is to package it for Debian and get it uploaded to Debian repositories. Going through the process of packaging itself is outside the scope of this tutorial. It is, however, well documented elsewhere. You should start here.

Debian packaging might seem like an unnecessary process that takes time with its adherence to standards, review process, legal checks, etc. However, upon close examination, one will find that without these steps the goals of the FreedomBox project cannot be met without such a process. Some of the advantages of Debian packaging are listed below:

Create a directory structure as follows with empty files. We will fill them up in a step-by-step manner.

+- <plinth_root>/
  |
  +- plinth/
  | |
  | +- modules/
  |   |
  |   +- ttrss/
  |     |
  |     +- __init__.py
  |     |
  |     +- forms.py
  |     |
  |     +- urls.py
  |     |
  |     +- views.py
  |     |
  |     +- templates/
  |     | |
  |     | +- ttrss.html
  |     |
  |     +- tests
  |       |
  |       +- __init__.py
  |
  +- actions/
  | |
  | +- ttrss
  |
  +- data/
    |
    +- etc/
      |
      +- plinth/
        |
        +- modules-enabled/
          |
          +- ttrss

The __init__.py indicates that the directory in which it is present is a Python module. For now, it is an empty file.

Plinth's setup script setup.py will automatically install the plinth/modules/ttrss directory (along with other files described later) to an appropriate location. If you are creating an application that stays independent and outside of Plinth source tree, then your setup.py script will need to install it a proper location on the system. The plinth/modules/ directory is a Python3 namespace package. So, you can install it with the plinth/modules/ directory structure into any Python path and still be discovered as plinth.modules.*.

The first thing to do is tell Plinth that our application exists. This is done by writing a small file with the Python import path to our application and placing it in data/etc/plinth/modules-enabled/. Let us create this file ttrss:

plinth.modules.ttrss

This file is automatically installed to /etc/plinth/modules-enabled/ by Plinth's installation script setup.py. If we are writing a module that resides independently outside the Plinth's source code, the setup script will need to copy it to the target location. Further, it is not necessary for the application to be part of the plinth.modules namespace. It can, for example, be plinth_ttrss.

For a user to visit our application in Plinth, we need to provide a URL. When the user visits this URL, a view is executed and a page is displayed. In urls.py write the following:

from django.conf.urls import patterns, url

urlpatterns = patterns(
    'plinth.modules.ttrss.views',
    url(r'^apps/ttrss/$', 'index', name='index'),
    )

This routes the /apps/ttrss/ URL to a view called index defined in plinth/modules/ttrss/views.py. This is no different than how routing URLs are written in Django. See Django URL dispatcher for more information.

We have added a URL to be handled by our application but this does not yet show up to be a link in Plinth web interface. Let us add a link in the applications list. In __init__.py add the following:

from plinth import cfg

def init():
    """Intialize the module."""
    menu = cfg.main_menu.get('apps:index')
    menu.add_urlname('News Feed Reader (Tiny Tiny RSS)', 'glyphicon-bullhorn',
                     'ttrss:index', 850)

As soon as Plinth starts, it will load all the enabled modules into memory. After this, it gives a chance to each of the modules to initialize itself by calling the init() method if there is such a method available as <app>.init(). Here we have implemented this method and added our menu item to the applications menu as part of the initialization process.

We wish to add our menu item to the list of applications which is why we have retrieved the applications menu which is available under the main menu. After this we add our own menu item to this menu. There are several parameters during this process that are important:

We have used the application menu item to insert our own menu item as a child. To be able to use the application menu item, we need to make sure that the module providing the application menu is loaded before our application is loaded. We will do that in the next step.

Specifying a simple list of applications to be loaded before our application provided to Plinth is sufficient. Add this in __init__.py.

depends = ['plinth.modules.apps']

Plinth will now make sure that the apps module is loaded before our module is loaded. Application initialization is also ensured to happen in this order. We can safely use any features of this module knowing that they have been initialized.

We wish to provide a user interface to the user to enable and disable the application. Complex modules may require more options but this is sufficient for our application. Add the following forms.py.

from django import forms

class TtrssForm(forms.Form):
    """Tiny Tiny RSS configuration form."""
    enabled = forms.BooleanField(
        label='Enable Tiny Tiny RSS',
        required=False)

This creates a Django form that shows a single option to enable/disable the application. It also shows its current state. This is how a regular Django form is built. See Django Forms documentation for more information.

In views.py, let us add a view that can handle the URL we have provided above.

from .forms import TtrssForm

def index(request):
    """Serve configuration page."""
    status = get_status()

    form = None

    if request.method == 'POST':
        form = TtrssForm(request.POST, prefix='ttrss')
        if form.is_valid():
            _apply_changes(request, status, form.cleaned_data)
            status = get_status()
            form = TtrssForm(initial=status, prefix='ttrss')
    else:
        form = TtrssForm(initial=status, prefix='ttrss')

    return TemplateResponse(request, 'ttrss.html',
                            {'title': 'News Feed Reader (Tiny Tiny RSS)',
                             'status': status,
                             'form': form})

This view works with the form we created in the previous step. It shows the current status of the service in form. This status is retrieved with the help of get_status() helper method. When the form is posted, again this view is called and it verifies whether the form's input values are correct. If so, it will apply the actions necessary for changed form values using the _apply_changes() method.

The view in the previous setup requires the status of the application to be retrieved using the get_status() method. Let us implement that method in views.py.

from plinth.modules import ttrss

def get_status():
    """Get the current status."""
    return {'enabled': ttrss.is_enabled()}

This method retrieves the various statuses of the application for display in the view. Currently, we only need to show whether the application is enabled or disabled. So, we retrieve that using a helper method defined in __init__.py.

from plinth import action_utils

def is_enabled():
    """Return whether the module is enabled."""
    return action_utils.webserver_is_enabled('50-tt-rss')

This method uses one of the several action utilities provided by Plinth. This method checks whether a webserver configuration named 50-tt-rss is enabled.

The view that we have written above requires a template file known as ttrss.html to work. This template file controls how the web page for our application is displayed. Let us create this template file in templates/ttrss.html.

{% extends "base.html" %}

{% load bootstrap %}

{% block content %}

<h2>News Feed Reader (Tiny Tiny RSS)</h2>

<p>Tiny Tiny RSS is a news feed (RSS/Atom) reader and aggregator,
  designed to allow you to read news from any location, while feeling
  as close to a real desktop application as possible.</p>

<h3>Configuration</h3>

<form class="form" method="post">
  {% csrf_token %}

  {{ form|bootstrap }}

  <input type="submit" class="btn btn-primary" value="Update setup"/>
</form>

{% endblock %}

This template extends an existing template known as base.html. This template is available in Plinth core to provide all the basic layout, styling, menus, JavaScript and CSS libraries. We will override the content area of the base template and keep the rest.

Yet again, there is nothing special about the way this template is written. This is a regular Django template. See Django Template documentation.

For styling and UI components, Plinth uses the Twitter Bootstrap project. See Bootstrap documentation for reference.

The view we have created displays the form and processes the form after the user submits it. It used a helper method called _apply_changes() to actually get the work done. Let us implement that method in views.py.

from django.contrib import messages

from plinth import actions

def _apply_changes(request, old_status, new_status):
    """Apply the changes."""
    modified = False

    if old_status['enabled'] != new_status['enabled']:
        sub_command = 'enable' if new_status['enabled'] else 'disable'
        actions.superuser_run('ttrss', [sub_command])
        modified = True

    if modified:
        messages.success(request, _('Configuration updated'))
    else:
        messages.info(request, _('Setting unchanged'))

We check to make sure that we don't try to disable the application when it is already disabled or try to enable the application when it is already enabled. Although Plinth's operations are idempotent, meaning that running them twice will not be problematic, we still wish avoid unnecessary operations for the sake of speed.

We are actually perform the operation using Plinth actions. We will implement the action to be performed a bit later.

After we perform the operation, we will show a message on the response page showing that the action was successful or that nothing happened. We use the Django messaging framework to accomplish this. See Django messaging framework for more information.

Plinth takes care of installing all the Debian packages required for our application to work. All we need to do is specify the list of the Debian packages required using a decorator on our view as follows:

from plinth import package

@package.required(['tt-rss'])
def index(request):
    """Serve configuration page."""
    ...

The first time this application's view is accessed, Plinth shows a package installation page and allows the user to install the required packages. After the package installation is completed, the user is shown the application's configuration page.

If there are configuration tasks to be performed immediately before or after the package installation, Plinth provides hooks for it. The before_install= and on_install= parameters to the @package.required decorator take a callback methods that are called before installation of packages and after installation of packages respectively. See the reference section of this manual or the plinth.package module for details. Other modules in Plinth that use this feature provided example usage.

The actual work of performing the configuration change is carried out by a Plinth action. Actions are independent scripts that run with higher privileges required to perform a task. They are placed in a separate directory and invoked as scripts via sudo. For our application we need to write an action that can enable and disable the web configuration. We will do this by creating a file actions/ttrss.

import argparse

from plinth import action_utils


def parse_arguments():
    """Return parsed command line arguments as dictionary."""
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers(dest='subcommand', help='Sub command')

    subparsers.add_parser('enable', help='Enable Tiny Tiny RSS')
    subparsers.add_parser('disable', help='Disable Tiny Tiny RSS')

    return parser.parse_args()


def subcommand_enable(_):
    """Enable web configuration and reload."""
    action_utils.webserver_enable('50-tt-rss')


def subcommand_disable(_):
    """Disable web configuration and reload."""
    action_utils.webserver_disable('50-tt-rss')


def main():
    """Parse arguments and perform all duties."""
    arguments = parse_arguments()

    subcommand = arguments.subcommand.replace('-', '_')
    subcommand_method = globals()['subcommand_' + subcommand]
    subcommand_method(arguments)


if __name__ == '__main__':
    main()

This is a simple Python3 program that parses command line arguments. While Python3 is preferred, it can be written in other languages also. It uses a helper utility provided by Plinth to actually enable and disable Apache2 web server configuration.

This script is automatically installed to /usr/share/plinth/actions by Plinth's installation script setup.py. Only from here will there is a possibility of running the script under sudo. If you are writing an application that resides indenpendently of Plinth's source code, your setup.py script will need to take care of copying the file to the target location.

Plinth provides a simple API for showing diagnostics results. The application has to implement a method for actually running the diagnostics and return the results as a list. Plinth then takes care of calling the diagnostics method and displaying the list in a formatted manner.

To implement the diagnostics method, method called diagnose() has to be available as <app>.diagnose(). It must return a list in which each item is the result of a test performed. The item itself is a two-tuple containing the display name of the test followed by the result as passed, failed or error.

def diagnose():
    """Run diagnostics and return the results."""
    results = []

    results.extend(action_utils.diagnose_url_on_all(
        'https://{host}/ttrss', extra_options=['--no-check-certificate']))

    return results

There are several helpers available to implement some of the common diagnostic tests. For our application we wish to implement a test to check whether the /ttrss URL is accessible. Since this is a commonly performed test, there is a helper method available and we have used it in the above code. The {host} tag replaced with various IP addresses, hostnames and domain names by the helper to produce different kinds of URLs and they are all tested. Results for all tests are returned which we then pass on to Plinth.

The user can trigger the diagnostics test by going to System -> Diagnostics page. This runs diagnostics for all the applications. If we want users to be able to run diagnostics specifically for this application, we can include a button for it in our template immediately after the application description.

{% include "diagnostics_button.html" with module="ttrss" %}

Sometimes we may feel the need to write some debug messages to the console and Plinth log file. Doing this in Plinth is just like doing this any other Python application.

import logging

logger = logging.getLogger(__name__)

def example_method():
    logger.debug('A debug level message')

    logger.info('Showing application page - %s', request.method)

    try:
        something()
    except Exception as exception:
        # Print stack trace
        logger.exception('Encountered an exception - %s', exception)

For more information see Python logging framework documentation.

Plinth is licensed under the GNU Affero General Public License Version 3 or later. FreedomBox UI applications, which run as modules under Plinth, also need to be under the same license or under a compatible license. The license of our application needs to clear for our application to be accepted by users and other developers. Let us add license headers to our application.

#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#

The above header needs to be present in every file of the application. It is suitable for Python files. However, in template files, we need to modify it slightly.

{% extends "base.html" %}
{% comment %}
#
# This file is part of Plinth.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
{% endcomment %}

...

Every string message that is visible to the user must localized to user's native language. For this to happen, our application needs to be internationalized. This requires marking the user visible messages for translation. Plinth applications use the gettext library to make that happen.

from gettext import gettext as _

def init():
    """Intialize the module."""
    menu = cfg.main_menu.get('apps:index')
    menu.add_urlname(_('News Feed Reader (Tiny Tiny RSS)'), 'glyphicon-envelope',
                     'ttrss:index', 600)

Notice that the menu item's display name is wrapped in the _() method call. Let us do that for the title of the application page too.

from gettext import gettext as _

def index(request):
    ...
    return TemplateResponse(request, 'ttrss.html',
                            {'title': _('News Feed Reader (Tiny Tiny RSS)'),
                             'status': status,
                             'form': form})

For readability and easy collaboration it is important to follow common coding standards. Plinth uses the Python coding standards and uses the pylint and flake8 tools to check if the there are any violations. Run these tools on our application and fix any errors and warnings. Better yet, integrate these tools into your favorite IDE for on-the-fly checking.

For the most part, the code we have written so far, is already compliant with the coding standards. This includes variable/method naming, indentation, document strings, comments, etc. One thing we have to add are the module documentation strings. Let us add those. In __init__.py add the top:

"""
Plinth module to configure Tiny Tiny RSS.
"""

These methods are optionally provided by the application and Plinth calls/uses them if they are present.

[('Check http://localhost/app is reachable', 'passed'),
 ('Check configuration is sane', 'passed')]

Plinth's web front does not directly change any aspect of the underlying operating system. Instead, it calls upon Actions, as shell commands. Actions live in /usr/share/plinth/actions directory. They require no interaction beyond passing command line arguments or taking sensitive arguments via stdin. They change the operation of the services and applications of the FreedomBox and nothing else. These actions are also directly usable by a skilled administrator.

The following methods are provided by Plinth to run actions and to implement them easily by reusing code for common tasks.

$ sudo apt-get install plinth

You may ask for support on

We are looking for help to improve Plinth. You can contribute to Plinth by not just by coding but also by translating, documenting, designing, packaging and providing support.

You may ask for support on

We are looking for help to improve FreedomBox Setup.

You may ask for support on

We are looking for help to improve Freedom Maker.