freedombone/website/EN/devguide.html

410 lines
16 KiB
HTML
Raw Normal View History

2016-10-12 17:06:43 +02:00
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
2018-02-07 11:48:03 +01:00
<!-- 2018-02-07 Wed 10:46 -->
2016-10-12 17:06:43 +02:00
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
2017-12-20 13:45:58 +01:00
<title>&lrm;</title>
2016-10-31 17:24:49 +01:00
<meta name="generator" content="Org mode" />
2016-10-12 17:06:43 +02:00
<meta name="author" content="Bob Mottram" />
<meta name="description" content="Turn the Beaglebone Black into a personal communications server"
/>
<meta name="keywords" content="freedombox, debian, beaglebone, red matrix, email, web server, home server, internet, censorship, surveillance, social network, irc, jabber" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
2017-07-01 21:24:04 +02:00
pre.src-hledger:before { content: 'hledger'; }
2016-10-12 17:06:43 +02:00
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }
/*]]>*/-->
</style>
<link rel="stylesheet" type="text/css" href="freedombone.css" />
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
2017-07-01 21:24:04 +02:00
Copyright (C) 2012-2017 Free Software Foundation, Inc.
2016-10-12 17:06:43 +02:00
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
</head>
<body>
<div id="preamble" class="status">
<a name="top" id="top"></a>
</div>
<div id="content">
<div class="org-center">
<div class="figure">
<p><img src="images/logo.png" alt="logo.png" />
</p>
</div>
</div>
<center><h1>Developers Guide</h1></center>
2018-02-07 11:48:03 +01:00
<div id="outline-container-orgcb772bb" class="outline-2">
<h2 id="orgcb772bb">Introduction</h2>
<div class="outline-text-2" id="text-orgcb772bb">
2016-10-13 00:03:59 +02:00
<p>
2018-02-06 23:30:44 +01:00
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 <a href="./codeofconduct.html">Code of Conduct</a>, and there is a Matrix room at <b>#fbone:matrix.freedombone.net</b>
2016-10-13 00:03:59 +02:00
</p>
</div>
</div>
2018-02-07 11:48:03 +01:00
<div id="outline-container-org8fd5474" class="outline-2">
<h2 id="org8fd5474">Adding extra apps</h2>
<div class="outline-text-2" id="text-org8fd5474">
2016-10-12 17:06:43 +02:00
<p>
2016-10-12 18:17:28 +02:00
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.
</p>
<p>
2018-02-06 22:56:15 +01:00
There's a command which you can use to generate scripts for new apps. Some examples are as follows:
</p>
<p>
To create a script for a generic PHP plus MySql/MariaDB web app:
2016-10-12 17:06:43 +02:00
</p>
<div class="org-src-container">
2018-02-06 23:00:15 +01:00
<pre class="src src-bash">freedombone-template --app [name] -e [email] -r [repo url] <span class="org-sh-escaped-newline">\</span>
-c [commit] --php yes -d mariadb &gt; <span class="org-sh-escaped-newline">\</span>
src/freedombone-app-myappname
2017-12-20 13:45:58 +01:00
</pre>
2016-10-12 17:06:43 +02:00
</div>
<p>
2018-02-06 22:56:15 +01:00
For a Nodejs app with MySql/MariaDB database:
2016-10-12 17:06:43 +02:00
</p>
<div class="org-src-container">
2018-02-06 23:00:15 +01:00
<pre class="src src-bash">freedombone-template --app [name] -e [email] -r [repo url] <span class="org-sh-escaped-newline">\</span>
-c [commit] --node yes -d mariadb <span class="org-sh-escaped-newline">\</span>
--dir /etc/myappname --daemon yes &gt; <span class="org-sh-escaped-newline">\</span>
src/freedombone-app-myappname
2017-12-20 13:45:58 +01:00
</pre>
2016-10-12 17:06:43 +02:00
</div>
<p>
2018-02-06 22:56:15 +01:00
For a Python app with Postgresql database:
2016-10-12 17:06:43 +02:00
</p>
<div class="org-src-container">
2018-02-06 23:00:15 +01:00
<pre class="src src-bash">freedombone-template --app [name] -e [email] -r [repo url] <span class="org-sh-escaped-newline">\</span>
-c [commit] -d postgresql <span class="org-sh-escaped-newline">\</span>
--dir /etc/myappname --daemon yes &gt; <span class="org-sh-escaped-newline">\</span>
src/freedombone-app-myappname
2017-12-20 13:45:58 +01:00
</pre>
2016-10-12 17:06:43 +02:00
</div>
<p>
2018-02-07 11:17:23 +01:00
For a Python app without any database, communicating between the daemon and the web server on port 1234:
2016-10-12 17:06:43 +02:00
</p>
<div class="org-src-container">
2018-02-06 23:00:15 +01:00
<pre class="src src-bash">freedombone-template --app [name] -e [email] -r [repo url] <span class="org-sh-escaped-newline">\</span>
-c [commit] --dir /etc/myappname <span class="org-sh-escaped-newline">\</span>
2018-02-07 11:17:23 +01:00
--daemon yes --portinternal 1234 &gt; <span class="org-sh-escaped-newline">\</span>
2018-02-06 23:00:15 +01:00
src/freedombone-app-myappname
2017-12-20 13:45:58 +01:00
</pre>
2016-10-12 17:06:43 +02:00
</div>
2018-02-07 11:48:03 +01:00
<p>
For an app without any database which communicates directly on a particular port through the firewall:
</p>
<div class="org-src-container">
<pre class="src src-bash">freedombone-template --app [name] -e [email] -r [repo url] <span class="org-sh-escaped-newline">\</span>
-c [commit] --dir /etc/myappname <span class="org-sh-escaped-newline">\</span>
--daemon yes --port 5000 &gt; <span class="org-sh-escaped-newline">\</span>
src/freedombone-app-myappname
</pre>
</div>
<p>
A generic PHP plus MySql/MariaDB web app which is only available on an onion address:
</p>
<div class="org-src-container">
<pre class="src src-bash">freedombone-template --app [name] -e [email] -r [repo url] <span class="org-sh-escaped-newline">\</span>
-c [commit] --php yes -d mariadb <span class="org-sh-escaped-newline">\</span>
--onion yes &gt; <span class="org-sh-escaped-newline">\</span>
src/freedombone-app-myappname
</pre>
</div>
2016-10-12 17:06:43 +02:00
<p>
2018-02-06 22:56:15 +01:00
For more details see the manpage:
2016-10-12 17:06:43 +02:00
</p>
2018-02-06 22:56:15 +01:00
<div class="org-src-container">
<pre class="src src-bash">man freedombone-template
</pre>
</div>
2018-02-07 11:27:50 +01:00
<p>
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 <b>install_app</b> function.
</p>
2016-10-12 17:06:43 +02:00
<p>
2018-02-06 22:56:15 +01:00
When your new script is ready for testing you can install it with:
2016-10-12 17:06:43 +02:00
</p>
<div class="org-src-container">
2018-02-06 22:56:15 +01:00
<pre class="src src-bash">make install
2017-12-20 13:45:58 +01:00
</pre>
2016-10-12 17:06:43 +02:00
</div>
<p>
2018-02-06 22:56:15 +01:00
Then run the administrator control panel and you should see the new app within <b>Add/Remove apps</b>.
2016-10-12 17:06:43 +02:00
</p>
<p>
2018-02-06 22:56:15 +01:00
Submit your working app to <b><a href="https://github.com/bashrc/freedombone/issues">https://github.com/bashrc/freedombone/issues</a></b> or create a pull request.
2016-10-12 17:06:43 +02:00
</p>
</div>
</div>
2016-10-13 00:03:59 +02:00
2018-02-07 11:48:03 +01:00
<div id="outline-container-orgaefd9da" class="outline-2">
<h2 id="orgaefd9da">Customising mesh images</h2>
<div class="outline-text-2" id="text-orgaefd9da">
2016-10-13 00:03:59 +02:00
<p>
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 <b>img/backgrounds</b> and to change the available avatars and desktop icons edit the images within <b>img/avatars</b>. Re-create disk images using the instructions shown previously.
</p>
<p>
If you need particular <i>dconf</i> commands to alter desktop appearance or behavior then see the function <i>mesh_client_startup_applications</i> within <b>src/freedombone-image-customise</b>.
</p>
</div>
</div>
2016-10-12 17:06:43 +02:00
</div>
<div id="postamble" class="status">
<style type="text/css">
.back-to-top {
position: fixed;
bottom: 2em;
right: 0px;
text-decoration: none;
color: #000000;
background-color: rgba(235, 235, 235, 0.80);
font-size: 12px;
padding: 1em;
display: none;
}
.back-to-top:hover {
background-color: rgba(135, 135, 135, 0.50);
}
</style>
<div class="back-to-top">
2016-10-31 17:24:49 +01:00
<a href="#top">Back to top</a> | <a href="mailto:bob@freedombone.net">E-mail me</a>
2016-10-12 17:06:43 +02:00
</div>
</div>
</body>
</html>