Developers Guide


Freedombone consists of a set of bash scripts. There are a lot of them, but they're not very complicated. If you're familiar with the GNU/Linux commandline and can hack a bash script then you can probably add a new app or fix a bug in the system. There are no trendy development frameworks to learn or to get in your way. You might also want to consult the Code of Conduct, and there is a Matrix room at and an XMPP multi-user chat at

Source code

If you just want to take a look at the source code then it can be found here or is obtainable on dat://c979feff64b9f69121b9e5659837de6792493b8aa362ab7401dff757cf54c870/

Creating images

Images are an easy way of distributing the software in a manner which avoids problems. These instructions assume that you're running either a Debian or Arch based distro.

sudo apt-get install git build-essential dialog
git clone
cd freedombone
git checkout stretch
sudo make install

Then install packages needed for building images:

freedombone-image --setup debian

or on an Arch/Parabola system:

freedombone-image --setup parabola

A typical use case to build an 8GB image for a Beaglebone Black is as follows. You can change the size depending upon the capacity of your microSD card.

freedombone-image -t beagleboneblack -s 8G

To build a 64bit Qemu image:

freedombone-image -t qemu-x86_64 -s 8G

Other supported boards are beaglebonegreen, beaglex15, cubieboard2, cubietruck, pcduino3, a20-olinuxino-lime, a20-olinuxino-lime2, a20-olinuxino-micro, banana-pro, i386, amd64, apu and qemu-i386.

If the image build fails with an error such as "Error reading from server. Remote end closed connection" then you can specify a debian package mirror repository manually with:

freedombone-image -t beagleboneblack -s 8G -m

Sometimes the build will fail just because a repo is temporarily unavailable. In that case just trying again may work.

Adding extra apps

Suppose you have some internet application which you want to add to the system. To do this you need to create an app script which tells the system how to install/remove and also backup/restore. The script should be designed to work with the current stable version of Debian.

There's a command which you can use to generate scripts for new apps. Some examples are as follows:

To create a script for a generic PHP plus MySql/MariaDB web app with a couple of extra packages:

freedombone-template --app [name] -e [email] -r [repo url] \
                     --packages "cowsay libssl-dev" \
                     -c [commit] --php yes -d mariadb > \

For a Nodejs app with MySql/MariaDB database:

freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] --node yes -d mariadb \
                     --dir /etc/myappname --daemon yes > \

For a Python app with Postgresql database:

freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] -d postgresql \
                     --dir /etc/myappname --daemon yes > \

For a Python app without any database, communicating between the daemon and the web server on port 1234:

freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] --dir /etc/myappname \
                     --daemon yes --portinternal 1234 > \

For an app without any database which communicates directly on a particular port through the firewall:

freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] --dir /etc/myappname \
                     --daemon yes --port 5000 > \

A generic PHP plus MySql/MariaDB web app which is only available on an onion address:

freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] --php yes -d mariadb \
                     --onion yes > \

For more details see the manpage:

man freedombone-template

The template command won't give you a fully working app, but it will give you a big head start and avoid a lot of potential mistakes. It's highly likely that you'll still need to add extra configuration for your particular app, especially within the install_app function.

When your new script is ready for testing you can install it with:

make install

Then run the administrator control panel and you should see the new app within Add/Remove apps.

Submit your working app to, create a pull request or if you don't have an account there you can send patches via email to

Customising mesh images

If you want to make your own specially branded version of the mesh images, such as for a particular event, then to change the default desktop backgrounds edit the images within img/backgrounds and to change the available avatars and desktop icons edit the images within img/avatars. Re-create disk images using the instructions shown previously.

If you need particular dconf commands to alter desktop appearance or behavior then see the function mesh_client_startup_applications within src/freedombone-image-customise.


Back to top | E-mail me