freedombonee/doc/EN/devguide.org

#+TITLE:
#+AUTHOR: Bob Mottram
#+EMAIL: bob@freedombone.net
#+KEYWORDS: freedombox, debian, beaglebone, red matrix, email, web server, home server, internet, censorship, surveillance, social network, irc, jabber
#+DESCRIPTION: Turn the Beaglebone Black into a personal communications server
#+OPTIONS: ^:nil toc:nil
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="freedombone.css" />

#+BEGIN_CENTER
[[file:images/logo.png]]
#+END_CENTER

#+begin_export html
<center><h1>Developers Guide</h1></center>
#+end_export

* Introduction
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 [[./codeofconduct.html][Code of Conduct]], and there is a Matrix room at *#fbone:matrix.freedombone.net*
* 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:

#+begin_src bash
freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] --php yes -d mariadb > \
                     src/freedombone-app-myappname
#+end_src

For a Nodejs app with MySql/MariaDB database:

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

For a Python app with Postgresql database:

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

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

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

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

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

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

#+begin_src bash
freedombone-template --app [name] -e [email] -r [repo url] \
                     -c [commit] --php yes -d mariadb \
                     --onion yes > \
                     src/freedombone-app-myappname
#+end_src

For more details see the manpage:

#+begin_src bash
man freedombone-template
#+end_src

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:

#+begin_src bash
make install
#+end_src

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

Submit your working app to *https://github.com/bashrc/freedombone/issues* or create a pull request.

* 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*.