From 553930da0d1799b5760cb3fc4107e737579970b5 Mon Sep 17 00:00:00 2001 From: Disassembler Date: Tue, 2 Jun 2020 08:41:14 +0200 Subject: [PATCH] Update docs with FrontlineSMS + comments in #337 --- doc/applications/frontlinesms.rst | 83 +++++++++++++++++++ doc/applications/index.rst | 1 + doc/applications/map-services.csv | 11 +-- doc/applications/map-services.rst | 2 +- .../sahana-configuration-report.rst | 4 +- doc/applications/sahana.rst | 4 +- doc/toolchain/abuild.rst | 4 +- doc/toolchain/spoc-builder.rst | 2 +- doc/toolchain/spoc-overview.rst | 2 +- doc/toolchain/spoc-user.rst | 2 +- doc/toolchain/virtual-machine-creation.rst | 4 +- doc/toolchain/virtual-machine-internals.rst | 2 +- doc/toolchain/vmmgr-internals.rst | 4 +- doc/toolchain/vmmgr-overview.rst | 4 +- 14 files changed, 104 insertions(+), 25 deletions(-) create mode 100644 doc/applications/frontlinesms.rst diff --git a/doc/applications/frontlinesms.rst b/doc/applications/frontlinesms.rst new file mode 100644 index 0000000..8318f04 --- /dev/null +++ b/doc/applications/frontlinesms.rst @@ -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 diff --git a/doc/applications/index.rst b/doc/applications/index.rst index 642facb..5d9a060 100644 --- a/doc/applications/index.rst +++ b/doc/applications/index.rst @@ -8,6 +8,7 @@ Applications and containers tech-knowledge map-services ckan + frontlinesms kanboard sahana sahana-configuration-report diff --git a/doc/applications/map-services.csv b/doc/applications/map-services.csv index ba79512..47f6f0e 100644 --- a/doc/applications/map-services.csv +++ b/doc/applications/map-services.csv @@ -1,6 +1,8 @@ Application,Data sources,Map viewer,Configurable,Notes CKAN,OSM (`Stamen `_),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 `_",Leaflet,No, EcoGIS,,FreeGIS + OpenLayers 2,Probably,[2] 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, Sahana Eden,OSM (`HOT `_),OpenLayers 2,"Yes, very",[5] Ushahidi,"OSM (`Mapbox `_, `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 (?),, diff --git a/doc/applications/map-services.rst b/doc/applications/map-services.rst index 7f9cfa3..c3a3278 100644 --- a/doc/applications/map-services.rst +++ b/doc/applications/map-services.rst @@ -8,5 +8,5 @@ Map services used in applications 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. 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 `_ 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. diff --git a/doc/applications/sahana-configuration-report.rst b/doc/applications/sahana-configuration-report.rst index 177a503..02d08aa 100644 --- a/doc/applications/sahana-configuration-report.rst +++ b/doc/applications/sahana-configuration-report.rst @@ -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. diff --git a/doc/applications/sahana.rst b/doc/applications/sahana.rst index f34fd05..5793cfd 100644 --- a/doc/applications/sahana.rst +++ b/doc/applications/sahana.rst @@ -4,9 +4,9 @@ Sahana Eden 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 `_. 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 `_. 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 `_. +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 `_. Upstream URL: https://github.com/sahana/eden diff --git a/doc/toolchain/abuild.rst b/doc/toolchain/abuild.rst index cd042ac..7b088f3 100644 --- a/doc/toolchain/abuild.rst +++ b/doc/toolchain/abuild.rst @@ -16,9 +16,9 @@ Usage of abuild, APK (*Alpine Package Keeper*) manager and syntax of ``APKBUILD` 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 `_. +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 `_. -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 `_. 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 `_. It is however perfectly suitable for packages installed directly on the basic VM. APKFILE and build example ------------------------- diff --git a/doc/toolchain/spoc-builder.rst b/doc/toolchain/spoc-builder.rst index e88530c..935fb57 100644 --- a/doc/toolchain/spoc-builder.rst +++ b/doc/toolchain/spoc-builder.rst @@ -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/userns.conf -For explanation of hooks and overall container integration and behavior, refer to `OverlayFS hooks `_ section on `SPOC Architecture `_ page. +For explanation of hooks and overall container integration and behavior, refer to `OverlayFS hooks `_ section on the `SPOC Architecture `_ page. Example build recipe -------------------- diff --git a/doc/toolchain/spoc-overview.rst b/doc/toolchain/spoc-overview.rst index c53d4a6..8643b87 100644 --- a/doc/toolchain/spoc-overview.rst +++ b/doc/toolchain/spoc-overview.rst @@ -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*. -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 `_ 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 `_ 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. diff --git a/doc/toolchain/spoc-user.rst b/doc/toolchain/spoc-user.rst index fe5cff7..9a526cd 100644 --- a/doc/toolchain/spoc-user.rst +++ b/doc/toolchain/spoc-user.rst @@ -4,7 +4,7 @@ SPOC user manual 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 `_ 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 `_ page. Images ------ diff --git a/doc/toolchain/virtual-machine-creation.rst b/doc/toolchain/virtual-machine-creation.rst index e99a650..138ffd9 100644 --- a/doc/toolchain/virtual-machine-creation.rst +++ b/doc/toolchain/virtual-machine-creation.rst @@ -65,8 +65,8 @@ Building the packages There are 3 distinct packaging systems. 1. Just a plain *tar.gz* for basic OS setup used by ``vm.sh`` installation script. -2. `Abuild `_ for the native Alpine linux packages (APK) used for ACME client and VMMgr packaging. -3. `SPOC `_ for SPOC container building and packaging. +2. `Abuild `_ for the native Alpine linux packages (APK) used for ACME client and VMMgr packaging. +3. `SPOC `_ 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. diff --git a/doc/toolchain/virtual-machine-internals.rst b/doc/toolchain/virtual-machine-internals.rst index 14eca73..256311b 100644 --- a/doc/toolchain/virtual-machine-internals.rst +++ b/doc/toolchain/virtual-machine-internals.rst @@ -42,4 +42,4 @@ Since the primary usage is expected to be in Central Europe, the terminal is exp 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 `_ 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 `_ for more detail on the nginx configuration. diff --git a/doc/toolchain/vmmgr-internals.rst b/doc/toolchain/vmmgr-internals.rst index 7d23fa0..b6d29ea 100644 --- a/doc/toolchain/vmmgr-internals.rst +++ b/doc/toolchain/vmmgr-internals.rst @@ -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 ``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 `_). 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 `_). 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 ^^^^^^ @@ -126,7 +126,7 @@ The template for individual applications looks as 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 `_). +Where the application name is taken from metadata and the upstream IP from SPOC global hosts file (see `Networking chapter in SPOC Architecture `_). The ``vmmgr_common`` is a file with several static rules diff --git a/doc/toolchain/vmmgr-overview.rst b/doc/toolchain/vmmgr-overview.rst index 9d7e995..7afef49 100644 --- a/doc/toolchain/vmmgr-overview.rst +++ b/doc/toolchain/vmmgr-overview.rst @@ -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 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 -------------- @@ -34,4 +34,4 @@ There is also a form to work with the HTTPS certificate on this page. The certif 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 `_ sections `SSH `_ and sections `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 `_ sections `SSH `_ and sections `WireGuard `_.