Update docs with FrontlineSMS + comments in #337

This commit is contained in:
Disassembler 2020-06-02 08:41:14 +02:00
parent 40e98ff42a
commit 553930da0d
Signed by: Disassembler
GPG Key ID: 524BD33A0EE29499
14 changed files with 104 additions and 25 deletions

View File

@ -0,0 +1,83 @@
FrontlineSMS
============
Overview
--------
FrontlineSMS is a system for both manual and automatic processing of SMS, supporting creation of various SMS workflows. The application is written in Java (resp. Groovy) and uses Grails layout engine. It has its own installer which deploys single-tenant Jetty lightweight applicaiton server. To work efficiently, FrontlineSMS requires a device with SMS capabilities or a connection to third-party service such as Twilio.
Upstream URL: https://github.com/frontlinesms/frontlinesms2
Modem capabilities
------------------
There are special considerations to be taken whenever an application witch direct access to hardware is run in a container. Currently FrontlineSMS has not been tested with such device and it is expected that some extra work or container configuration not present in any other application needs to be done in order to make the hardware device available and usable by the container.
X server
--------
Although FrontlineSMS is a web application, it requires X server as it attempts to install a systray icon. On a headless server, this requirement can be worked around using ``xf86-video-dummy`` package which works as a *blackhole* display driver.
The X server is then started as
.. code-block:: bash
Xorg -noreset +extension GLX +extension RANDR +extension RENDER -config dummy.conf :10
Where the ``dummy.conf`` looks as follows
.. code-block:: xorg.conf
Section "ServerFlags"
Option "DontVTSwitch" "true"
Option "AllowMouseOpenFail" "true"
Option "PciForceNone" "true"
Option "AutoEnableDevices" "false"
Option "AutoAddDevices" "false"
EndSection
Section "InputDevice"
Identifier "dummy_mouse"
Option "CorePointer" "true"
Driver "void"
EndSection
Section "InputDevice"
Identifier "dummy_keyboard"
Option "CoreKeyboard" "true"
Driver "void"
EndSection
Section "Device"
Identifier "dummy_videocard"
Driver "dummy"
Option "ConstantDPI" "true"
VideoRam 192000
EndSection
Section "Monitor"
Identifier "dummy_monitor"
HorizSync 5.0 - 1000.0
VertRefresh 5.0 - 200.0
Modeline "1280x720" 27.41 1280 1312 1416 1448 720 737 740 757
EndSection
Section "Screen"
Identifier "dummy_screen"
Device "dummy_videocard"
Monitor "dummy_monitor"
DefaultDepth 24
SubSection "Display"
Viewport 0 0
Depth 24
Modes "1280x720"
Virtual 8192 4096
EndSubSection
EndSection
Section "ServerLayout"
Identifier "dummy_layout"
Screen "dummy_screen"
InputDevice "dummy_mouse"
InputDevice "dummy_keyboard"
EndSection

View File

@ -8,6 +8,7 @@ Applications and containers
tech-knowledge tech-knowledge
map-services map-services
ckan ckan
frontlinesms
kanboard kanboard
sahana sahana
sahana-configuration-report sahana-configuration-report

View File

@ -1,6 +1,8 @@
Application,Data sources,Map viewer,Configurable,Notes Application,Data sources,Map viewer,Configurable,Notes
CKAN,OSM (`Stamen <http://maps.stamen.com>`_),Leaflet,No,[1] CKAN,OSM (`Stamen <http://maps.stamen.com>`_),Leaflet,No,[1]
CrisisCleanup,Google Maps,Google Maps,No, CrisisCleanup v2,Google Maps,Google Maps,No,
CrisisCleanup v3,OSM,Leaflet,No,
Crismapp,OSM,Leaflet,,
CTS,"OSM, `ArcGIS <http://server.arcgisonline.com/arcgis/rest/services>`_",Leaflet,No, CTS,"OSM, `ArcGIS <http://server.arcgisonline.com/arcgis/rest/services>`_",Leaflet,No,
EcoGIS,,FreeGIS + OpenLayers 2,Probably,[2] EcoGIS,,FreeGIS + OpenLayers 2,Probably,[2]
Odoo,Google Maps,Google Maps,No,[3] Odoo,Google Maps,Google Maps,No,[3]
@ -8,10 +10,3 @@ OpenMapKit,OSM,N/A,Yes,[4]
Pan.do/ra,Google Maps,Google Maps + OxMap,No, Pan.do/ra,Google Maps,Google Maps + OxMap,No,
Sahana Eden,OSM (`HOT <https://www.hotosm.org/>`_),OpenLayers 2,"Yes, very",[5] Sahana Eden,OSM (`HOT <https://www.hotosm.org/>`_),OpenLayers 2,"Yes, very",[5]
Ushahidi,"OSM (`Mapbox <https://www.mapbox.com/about/maps/>`_, `HOT`_)",Leaflet,No, Ushahidi,"OSM (`Mapbox <https://www.mapbox.com/about/maps/>`_, `HOT`_)",Leaflet,No,
*---*,,,,
WebODM,OSM,Leaflet,,
Crismapp,OSM,Leaflet,,
ThinkHazard!,OSM,Mapbox,,
Openforis,Google Earth,,No,
Tendenci,Google Maps,Google Maps,No,
GeoNode,OSM,OpenLayers 3 (?),,

1 Application Data sources Map viewer Configurable Notes
2 CKAN OSM (`Stamen <http://maps.stamen.com>`_) Leaflet No [1]
3 CrisisCleanup CrisisCleanup v2 Google Maps Google Maps No
4 CrisisCleanup v3 OSM Leaflet No
5 Crismapp OSM Leaflet
6 CTS OSM, `ArcGIS <http://server.arcgisonline.com/arcgis/rest/services>`_ Leaflet No
7 EcoGIS FreeGIS + OpenLayers 2 Probably [2]
8 Odoo Google Maps Google Maps No [3]
10 Pan.do/ra Google Maps Google Maps + OxMap No
11 Sahana Eden OSM (`HOT <https://www.hotosm.org/>`_) OpenLayers 2 Yes, very [5]
12 Ushahidi OSM (`Mapbox <https://www.mapbox.com/about/maps/>`_, `HOT`_) Leaflet No
*---*
WebODM OSM Leaflet
Crismapp OSM Leaflet
ThinkHazard! OSM Mapbox
Openforis Google Earth No
Tendenci Google Maps Google Maps No
GeoNode OSM OpenLayers 3 (?)

View File

@ -8,5 +8,5 @@ Map services used in applications
1. Used by CKAN extensions *reclineview*, *spatial* and *geoview*. 1. Used by CKAN extensions *reclineview*, *spatial* and *geoview*.
2. Untested as the EcoGIS source code is not fully open. Looks like the data sources are configurable, but the full documentation is only in Italian. 2. Untested as the EcoGIS source code is not fully open. Looks like the data sources are configurable, but the full documentation is only in Italian.
3. Used by Odoo *Google Maps* module to display company/partner address on map. 3. Used by Odoo *Google Maps* module to display company/partner address on map.
4. Map is used by OMK and ODK Android clients. OMK Server only offers the API. See `area of interest deployment <http://posm.io/docs/omk/walkthrough/>`_ on POSM wiki. 4. Map is used by OMK and ODK Android clients. OMK Server only offers API.
5. Sahana Eden supports multitude of connectors and protocols to process map and feature data. ArcGIS REST, Bing maps, GeoJSON, GeoRSS, Google Maps, GPX, KML, MGRS, OSM, OWM, Shapefile, TMS, WFS, WMS and XYZ. 5. Sahana Eden supports multitude of connectors and protocols to process map and feature data. ArcGIS REST, Bing maps, GeoJSON, GeoRSS, Google Maps, GPX, KML, MGRS, OSM, OWM, Shapefile, TMS, WFS, WMS and XYZ.

View File

@ -1,5 +1,5 @@
Sahana Eden configuration and modules usability report Sahana Eden configuration usability report
====================================================== ==========================================
This document aims to provide comprehensive overview about status and usability of Sahana Eden configuration directives and modules, including the explanation of any deviation from the expected state, encountered errors and stack traces where applicable. Secondary function of this document is to provide a list of possible configuration directives and their expected types, values and effects. However the list is primarily collected using the directives present in *config.py* file in *default* template and is not exhaustive. This document aims to provide comprehensive overview about status and usability of Sahana Eden configuration directives and modules, including the explanation of any deviation from the expected state, encountered errors and stack traces where applicable. Secondary function of this document is to provide a list of possible configuration directives and their expected types, values and effects. However the list is primarily collected using the directives present in *config.py* file in *default* template and is not exhaustive.

View File

@ -4,9 +4,9 @@ Sahana Eden
Overview Overview
-------- --------
Sahana Eden is a flexible and extensible humanitarian platform written in python, running on web2py platform and PostgreSQL with PostGIS extension. Sahana Eden is extremely highly customizable and configurable which unfortunately often leads to various bugs and misunderstandings in the configuration. For the description of the individual configuration options and their effect, see `Sahana configuration report <sahana-configuration-report>`_. The application is usually configured via templates, which contain all the configuration, forms and logic customizations and some basic data relevant for the intended deployment. Sahana Eden is a flexible and extensible humanitarian platform written in python, running on web2py platform and PostgreSQL with PostGIS extension. Sahana Eden is extremely highly customizable and configurable which unfortunately often leads to various bugs and misunderstandings in the configuration. For the description of the individual configuration options and their effect, see `Sahana Eden configuration usability report <sahana-configuration-report.html>`_. The application is usually configured via templates, which contain all the configuration, forms and logic customizations and some basic data relevant for the intended deployment.
The application supports various interfaces, protocols and formats for data exchange - CAP (Common Alerting Protocol), XML/Atom feeds, WMS, WFS, WCS and other map services, KML exports, XML and CSV tabular data etc. Maps can be configured and adjusted to use virtually any tile, layer and feature sets. See `map services <map-services>`_. The application supports various interfaces, protocols and formats for data exchange - CAP (Common Alerting Protocol), XML/Atom feeds, WMS, WFS, WCS and other map services, KML exports, XML and CSV tabular data etc. Maps can be configured and adjusted to use virtually any tile, layer and feature sets. See `map services <map-services.html>`_.
Upstream URL: https://github.com/sahana/eden Upstream URL: https://github.com/sahana/eden

View File

@ -16,9 +16,9 @@ Usage of abuild, APK (*Alpine Package Keeper*) manager and syntax of ``APKBUILD`
Abuild in a nutshell Abuild in a nutshell
-------------------- --------------------
Building with abuild requires ``alpine-sdk`` package installed, ``/etc/abuild.conf`` configured and an RSA private key created in ``/root/repo.spotter.cz.rsa`` and subsequently registered by ``abuild-keygen`` command. All these are taken care of in ``install-toolchain.sh`` script as part of `Build environment installation <vm-creation>`_. Building with abuild requires ``alpine-sdk`` package installed, ``/etc/abuild.conf`` configured and an RSA private key created in ``/root/repo.spotter.cz.rsa`` and subsequently registered by ``abuild-keygen`` command. All these are taken care of in ``install-toolchain.sh`` script as part of `Build environment installation <virtual-machine-creation.html#build-environment-installation>`_.
Abuild toolchain is intended to be used in automated builds, therefore it requires some dependencies normally not found in other packaging systems. Abuild expects that ``APKBUILD`` files are a part of git repository and tries to read current commit hash. Then it tries to automatically download, build (compile), strip symbols binaries, find out dependencies, and generally perform a lot of tasks normally useful when you are compiling binaries from sources. Finally it packages the result to one or more subpackages, according to the build recipe. For purposes of SPOC containers packaging, this is mostly useless, which is the reason why we have a `custom package manager <spoc>`_. It is however perfectly suitable for packages installed directly on the basic VM. Abuild toolchain is intended to be used in automated builds, therefore it requires some dependencies normally not found in other packaging systems. Abuild expects that ``APKBUILD`` files are a part of git repository and tries to read current commit hash. Then it tries to automatically download, build (compile), strip symbols binaries, find out dependencies, and generally perform a lot of tasks normally useful when you are compiling binaries from sources. Finally it packages the result to one or more subpackages, according to the build recipe. For purposes of SPOC containers packaging, this is mostly useless, which is the reason why we have a `custom package manager <spoc-overview.html#package-manager>`_. It is however perfectly suitable for packages installed directly on the basic VM.
APKFILE and build example APKFILE and build example
------------------------- -------------------------

View File

@ -225,7 +225,7 @@ Although SPOC populates some LXC config fields, there are lot of defaults with r
lxc.include = /usr/share/lxc/config/common.conf lxc.include = /usr/share/lxc/config/common.conf
lxc.include = /usr/share/lxc/config/userns.conf lxc.include = /usr/share/lxc/config/userns.conf
For explanation of hooks and overall container integration and behavior, refer to `OverlayFS hooks <spoc-architecture>`_ section on `SPOC Architecture <spoc-architecture>`_ page. For explanation of hooks and overall container integration and behavior, refer to `OverlayFS hooks <spoc-architecture.html#overlayfs-hooks>`_ section on the `SPOC Architecture <spoc-architecture.html>`_ page.
Example build recipe Example build recipe
-------------------- --------------------

View File

@ -35,7 +35,7 @@ Docker requires a daemon to run at all times. Whenever the daemon needs to be st
Finally, Docker maintainers explicitly refuse to implement a feature which would allow to restrict the Docker daemon to private repositories (registries) in the community edition of Docker (*Docker Enterprise* allows this). It is possible to have custom and even private repositories, but it is not possible to deactivate the default public *Dockerhub*. Finally, Docker maintainers explicitly refuse to implement a feature which would allow to restrict the Docker daemon to private repositories (registries) in the community edition of Docker (*Docker Enterprise* allows this). It is possible to have custom and even private repositories, but it is not possible to deactivate the default public *Dockerhub*.
The downside of using LXC is that its usage requires more knowledge about how the linux containers actually work. Another problem is fast availability of the desired image as most 3rd party applications are shipped with `Dockerfile` or directly distributed as Docker images. SPOC/LXC requires rewriting into LXC-compatible containers, however this is simplified by SPOC as the `image building <spoc-builder>`_ aims to mimic the features of Docker and automatize LXC container building using *Dockerfile*-like syntax. The downside of using LXC is that its usage requires more knowledge about how the linux containers actually work. Another problem is fast availability of the desired image as most 3rd party applications are shipped with `Dockerfile` or directly distributed as Docker images. SPOC/LXC requires rewriting into LXC-compatible containers, however this is simplified by SPOC as the `image building <spoc-builder.html>`_ aims to mimic the features of Docker and automatize LXC container building using *Dockerfile*-like syntax.
In the future, LXC and part of SPOC may be replaced by Podman and Podman-compose to reach even wider audience. In the future, LXC and part of SPOC may be replaced by Podman and Podman-compose to reach even wider audience.

View File

@ -4,7 +4,7 @@ SPOC user manual
Usage Usage
----- -----
In order to consume the images and applications from online repositories, the user needs to set up the online repository URL and ECDSA public key in their ``/etc/spoc/spoc.conf`` file. The configuration file directives are covered on the `architecture <spoc-architecture>`_ page. In order to consume the images and applications from online repositories, the user needs to set up the online repository URL and ECDSA public key in their ``/etc/spoc/spoc.conf`` file. The configuration file directives are covered on the `architecture <spoc-architecture.html>`_ page.
Images Images
------ ------

View File

@ -65,8 +65,8 @@ Building the packages
There are 3 distinct packaging systems. There are 3 distinct packaging systems.
1. Just a plain *tar.gz* for basic OS setup used by ``vm.sh`` installation script. 1. Just a plain *tar.gz* for basic OS setup used by ``vm.sh`` installation script.
2. `Abuild <abuild>`_ for the native Alpine linux packages (APK) used for ACME client and VMMgr packaging. 2. `Abuild <abuild.html>`_ for the native Alpine linux packages (APK) used for ACME client and VMMgr packaging.
3. `SPOC <spoc>`_ for SPOC container building and packaging. 3. `SPOC <spoc.html>`_ for SPOC container building and packaging.
Before any building and packaging can be started, build toolchain including signing keys needs to be set up. This is done via ``install-toolchain.sh`` script. Before any building and packaging can be started, build toolchain including signing keys needs to be set up. This is done via ``install-toolchain.sh`` script.

View File

@ -42,4 +42,4 @@ Since the primary usage is expected to be in Central Europe, the terminal is exp
Web server Web server
---------- ----------
By default, the only access to any VM features is available only through VMMgr, which runs as a standalone WSGI application. All access passes through *nginx* web server which serves as reverse proxy. See `VMMgr internals <vmmgr-internals>`_ for more detail on the nginx configuration. By default, the only access to any VM features is available only through VMMgr, which runs as a standalone WSGI application. All access passes through *nginx* web server which serves as reverse proxy. See `VMMgr internals <vmmgr-internals.html#nginx-configuration>`_ for more detail on the nginx configuration.

View File

@ -33,7 +33,7 @@ host
The ``host`` part in ``domain`` and ``port`` fields holds easily parsable information about the main HTTP host on which the VMMgr is accessible. This configuration is supplied to other services and tools such as nginx and `Issue / MotD`_ banners. The HTTP host component is also used in conjunction with the application subdomain to form the FQDN for the separate applications which the nginx reverse proxy accepts. The ``host`` part in ``domain`` and ``port`` fields holds easily parsable information about the main HTTP host on which the VMMgr is accessible. This configuration is supplied to other services and tools such as nginx and `Issue / MotD`_ banners. The HTTP host component is also used in conjunction with the application subdomain to form the FQDN for the separate applications which the nginx reverse proxy accepts.
The ``adminpwd`` part is *argon2* hash of the VMMgr administrator password which is designed to be the same as the LUKS disk encryption password (see `Virtual Machine internals <virtual-machine-internals>`_). However, there isn't any direct link between these two and VMMgr always attempts to modify both passwords at once, leveraging the return code of ``cryptsetup luksChangeKey`` to obtain the information about whether the user managed to supply the correct old password. The ``adminpwd`` part is *argon2* hash of the VMMgr administrator password which is designed to be the same as the LUKS disk encryption password (see `Virtual Machine internals <virtual-machine-internals.html#disk-partitioning>`_). However, there isn't any direct link between these two and VMMgr always attempts to modify both passwords at once, leveraging the return code of ``cryptsetup luksChangeKey`` to obtain the information about whether the user managed to supply the correct old password.
common common
^^^^^^ ^^^^^^
@ -126,7 +126,7 @@ The template for individual applications looks as
include vmmgr_common; include vmmgr_common;
} }
Where the application name is taken from metadata and the upstream IP from SPOC global hosts file (see `Networking chapter in SPOC Architecture <spoc-architecture#networking>`_). Where the application name is taken from metadata and the upstream IP from SPOC global hosts file (see `Networking chapter in SPOC Architecture <spoc-architecture.html#networking>`_).
The ``vmmgr_common`` is a file with several static rules The ``vmmgr_common`` is a file with several static rules

View File

@ -3,7 +3,7 @@ VMMgr overview
VMMgr is simply a **Virtual Machine Manager**, a web interface for interaction with the virtual machine and SPOC. It offers user friendly frontend for the commonly used features of the virtual machine. VMMgr is simply a **Virtual Machine Manager**, a web interface for interaction with the virtual machine and SPOC. It offers user friendly frontend for the commonly used features of the virtual machine.
VMMgr is a WSGI application written in python 3.7 and running as standalone service employing werkzeug HTTP server. VMMgr is not a mandatory component for SPOC, respective applications and containers, it is only a web interface to conveniently manage the whole virtual appliance. VMMgr is a WSGI application written in python 3.7 and running as standalone service employing werkzeug HTTP server. VMMgr is not a mandatory component for SPOC, respective applications and containers, it is only a web interface to conveniently manage the whole virtual appliance. The current version, interfaces, endpoints and general look and feel of the application is only provisionary to demostrate the intended capabilities. It's currently available only in Czech and alhtough it's mostly ready to be translated, doing so at this point in development would be a wasted effort.
Authentication Authentication
-------------- --------------
@ -34,4 +34,4 @@ There is also a form to work with the HTTPS certificate on this page. The certif
Remote access settings Remote access settings
---------------------- ----------------------
These settings allow to configure remote administration via SSH and remote access via WireGuard VPN. The remote access settings are intended for advanced administration. For more details on usage, see `VMMgr internals <vmmgr-internals>`_ sections `SSH <vmmgr-internals#ssh>`_ and sections `WireGuard <vmmgr-internals#wireguard>`_. These settings allow to configure remote administration via SSH and remote access via WireGuard VPN. The remote access settings are intended for advanced administration. For more details on usage, see `VMMgr internals <vmmgr-internals.html>`_ sections `SSH <vmmgr-internals.html#ssh>`_ and sections `WireGuard <vmmgr-internals.html#wireguard>`_.