From 40e98ff42ab1513dce58a0696182f7d429382528 Mon Sep 17 00:00:00 2001 From: Disassembler Date: Mon, 1 Jun 2020 22:05:55 +0200 Subject: [PATCH] Update technical documentation --- apk/spoc | 2 +- build/install-toolchain.sh | 1 - doc/applications/ckan.rst | 78 + doc/applications/images-list-apps.csv | 21 + doc/applications/images-list-basic.csv | 13 + doc/applications/images-list-services.csv | 8 + doc/applications/images-list.rst | 25 + doc/applications/index.rst | 14 + doc/applications/kanboard.rst | 121 ++ doc/applications/map-services.csv | 17 + doc/applications/map-services.rst | 12 + .../sahana-configuration-report.rst | 1490 +++++++++++++++++ doc/applications/sahana.rst | 21 + doc/applications/seeddms.rst | 70 + .../tech-knowledge.rst} | 190 ++- doc/conf.py | 37 +- doc/existing/index.rst | 9 - doc/existing/list.md | 57 - doc/existing/map-services.md | 27 - doc/index.rst | 2 +- doc/toolchain/abuild.md | 49 - doc/toolchain/abuild.rst | 53 + doc/toolchain/index.rst | 18 +- doc/toolchain/lxc-build.md | 183 -- doc/toolchain/lxc-overview.md | 71 - doc/toolchain/lxc-pack.md | 78 - doc/toolchain/pkgmgr.md | 73 - doc/toolchain/spoc-architecture.rst | 179 ++ doc/toolchain/spoc-builder.rst | 371 ++++ doc/toolchain/spoc-overview.rst | 130 ++ doc/toolchain/spoc-user.rst | 275 +++ doc/toolchain/virtual-machine-creation.rst | 73 + doc/toolchain/virtual-machine-internals.rst | 45 + doc/toolchain/vm-creation.md | 65 - doc/toolchain/vmmgr-hooks.md | 90 - doc/toolchain/vmmgr-internals.rst | 207 +++ doc/toolchain/vmmgr-overview.rst | 37 + 37 files changed, 3397 insertions(+), 815 deletions(-) create mode 100644 doc/applications/ckan.rst create mode 100644 doc/applications/images-list-apps.csv create mode 100644 doc/applications/images-list-basic.csv create mode 100644 doc/applications/images-list-services.csv create mode 100644 doc/applications/images-list.rst create mode 100644 doc/applications/index.rst create mode 100644 doc/applications/kanboard.rst create mode 100644 doc/applications/map-services.csv create mode 100644 doc/applications/map-services.rst create mode 100644 doc/applications/sahana-configuration-report.rst create mode 100644 doc/applications/sahana.rst create mode 100644 doc/applications/seeddms.rst rename doc/{existing/tech-overview.md => applications/tech-knowledge.rst} (75%) delete mode 100644 doc/existing/index.rst delete mode 100644 doc/existing/list.md delete mode 100644 doc/existing/map-services.md delete mode 100644 doc/toolchain/abuild.md create mode 100644 doc/toolchain/abuild.rst delete mode 100644 doc/toolchain/lxc-build.md delete mode 100644 doc/toolchain/lxc-overview.md delete mode 100644 doc/toolchain/lxc-pack.md delete mode 100644 doc/toolchain/pkgmgr.md create mode 100644 doc/toolchain/spoc-architecture.rst create mode 100644 doc/toolchain/spoc-builder.rst create mode 100644 doc/toolchain/spoc-overview.rst create mode 100644 doc/toolchain/spoc-user.rst create mode 100644 doc/toolchain/virtual-machine-creation.rst create mode 100644 doc/toolchain/virtual-machine-internals.rst delete mode 100644 doc/toolchain/vm-creation.md delete mode 100644 doc/toolchain/vmmgr-hooks.md create mode 100644 doc/toolchain/vmmgr-internals.rst create mode 100644 doc/toolchain/vmmgr-overview.rst diff --git a/apk/spoc b/apk/spoc index 021bac4..7b3c208 160000 --- a/apk/spoc +++ b/apk/spoc @@ -1 +1 @@ -Subproject commit 021bac46b39ef25b0daea1eb6c4ee0c38160a89f +Subproject commit 7b3c2088e12516a5f1901f92db68602f911f1245 diff --git a/build/install-toolchain.sh b/build/install-toolchain.sh index 53b6d75..24d6126 100755 --- a/build/install-toolchain.sh +++ b/build/install-toolchain.sh @@ -10,7 +10,6 @@ apk add git file htop less openssh-client tree apk add alpine-sdk # Install Sphinx support apk add py3-sphinx -pip3 install recommonmark sphinx-markdown-tables # Copy root profile files and settings mkdir -p /root/.config/htop diff --git a/doc/applications/ckan.rst b/doc/applications/ckan.rst new file mode 100644 index 0000000..3b2da10 --- /dev/null +++ b/doc/applications/ckan.rst @@ -0,0 +1,78 @@ +CKAN +==== + +Overview +-------- + +CKAN is an open-source DMS (data management system) for powering data hubs and data portals. CKAN makes it easy to publish, share and use data. It is written in python, has Flask-based web interface and uses Postgres database with PostGIS extension. CKAN exposes API which allows third parties to create extensions. + +The project is split to several components. The most important ones are: + +- **ckan** - https://github.com/ckan/ckan - The main DMS component with Flask frontend. +- **datapusher** - https://github.com/ckan/datapusher - A standalone web service that pushes data files from a CKAN site's resources into its DataStore. +- **ckan-service-provider** - https://github.com/ckan/ckan-service-provider - A library for making web services that make functions available as synchronous or asynchronous jobs. + +Apart from that, CKAN requires a *Redis* in-memory data store and *Solr* search platform instance. Note that CKAN is shipped with Solr schemas which don't work well with up-to-date versions of Solr, therefore we use older Solr 6.5.1. + +DataPusher +---------- + +DataPusher is running as a separate service. Its development is a bit out of sync with the core ckan component. SKAN has already moved to python 3, however datapusher is still working only with python 2.7. Due to that, DataPusher has its own image and is running as a separate container. + +Alpine, being a progressive linux distribution, stopped supporting uwsgi connector for python 2.7 in Alpine 3.11, therefore the container needs to be based on older Alpine 3.10 which still ships with *uwsgi-python2*. + +The connection between CKAN and DataPusher is done via HTTPS endpoints. There is a possibility to disable TLS certificate verification, but a better solution seems to be import any self-signed certificate into the DataPusher's trust store. There is a script which automatically handles the import whenever the DataPusher container starts. + +Extensions +---------- + +CKAN container comes with several preinstalled and preconfigured extensions. Historically, there were more extensions, but over the time CKAN's API evolved and the development has moved to python 3, so majority of the historical extensions are no longer operational. + +ckan/ckanext-basiccharts +^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/ckan/ckanext-basiccharts + +Adds Line, Bar and Pie charts. It uses Flot Charts, which is compatible with all major browsers (including IE6+). + +ckan/ckanext-spatial +^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/ckan/ckanext-spatial + +Contains plugins that add geospatial capabilities to CKAN. E.g. a spatial field on the default CKAN dataset schema which allows to perform spatial queries and to display the dataset extent on the frontend. + +ckan/ckanext-geoview +^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/ckan/ckanext-geoview + +Contains view plugins to display geospatial files and services in CKAN. It contains an OpenLayers based viewer and other view plugins that used to be part of ckanext-spatial. + +ckan/ckanext-mapviews +^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/ckan/ckanext-mapviews + +Adds regular and choropleth maps to CKAN, using the new CKAN Resource View. It uses LeafletJS, which is compatible with all major browsers (including IE7+). + +XVTSolutions/ckanext-spatialUI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/XVTSolutions/ckanext-spatialUI + +Provides the UI elements for spatial search. Spatial search widget and dataset extent map. + +aptivate/ckanext-datasetthumbnail +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/aptivate/ckanext-datasetthumbnail + +Adds support for generation and display of thumbnail images. + +datagvat/ckanext-dgvat_xls +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/datagvat/ckanext-dgvat_xls + +Allows group admin to export datasets from their organizations to export all datasets to a .xls worksheet. Sysadmins may choose to export datasets from any organization they want or to export all datasets of all groups. diff --git a/doc/applications/images-list-apps.csv b/doc/applications/images-list-apps.csv new file mode 100644 index 0000000..1ca9eda --- /dev/null +++ b/doc/applications/images-list-apps.csv @@ -0,0 +1,21 @@ +Application,Container,Host +CKAN,ckan,ckan +Crisis Cleanup,crisiscleanup,cc +CTS,cts,cts +EcoGIS,ecogis,ecogis +FrontlineSMS,frontlinesms,sms +GNU Health,gnuhealth,gh +Kanboard,kanboard,kb +Mifos X,mifosx,mifosx +Motech,motech,motech +ODK Aggregate,opendatakit,odk +ODK Build,opendatakit-build,odkbuild +Odoo,odoo,odoo +OpenMapKit,openmapkit,omk +Pan.do/ra,pandora,pandora +Sahana,sahana,sahana +Sahana - Demo,sahana-demo,sahana-demo +SAMBRO,sambro,sambro +SeedDMS,seeddms,dms +Sigmah,sigmah,sigmah +Ushahidi,ushahidi,ush diff --git a/doc/applications/images-list-basic.csv b/doc/applications/images-list-basic.csv new file mode 100644 index 0000000..f7c1330 --- /dev/null +++ b/doc/applications/images-list-basic.csv @@ -0,0 +1,13 @@ +Product,Layer +Alpine 3.8,alpine3.8 +Alpine 3.8 - PHP 5.6,alpine3.8-php5.6 +Alpine 3.9 - Ruby 2.4,alpine3.8-ruby2.4 +Alpine 3.9,alpine3.9 +Alpine 3.9 - Java 8,alpine3.9-java8 +Alpine 3.9 - PHP 7.2,alpine3.9-php7.2 +Alpine 3.9 - Python 2.7,alpine3.9-python2.7 +Alpine 3.9 - Python 3.6,alpine3.9-python3.6 +Alpine 3.9 - Ruby 2.4,alpine3.9-ruby2.4 +Alpine 3.9 - Ruby 2.6,alpine3.9-ruby2.6 +Alpine 3.9 - Tomcat 7,alpine3.9-tomcat7 +Alpine 3.9 - Tomcat 8.5,alpine3.9-tomcat8.5 diff --git a/doc/applications/images-list-services.csv b/doc/applications/images-list-services.csv new file mode 100644 index 0000000..ed1b0f2 --- /dev/null +++ b/doc/applications/images-list-services.csv @@ -0,0 +1,8 @@ +Product,Layer,UID/GID,Internal Port +ActiveMQ,activemq,61616,61616 (ActiveMQ) +MariaDB,mariadb,3306,3306 (MySQL) +Postgres,postgres,5432,5432 (Postgres) +PostGIS,postgis,5432,5432 (Postgres) +RabbitMQ,rabbitmq,5672,5672 (AMQP) +Redis,redis,6379,6379 (Redis) +Solr 6,solr6,8983,8983 (HTTP) diff --git a/doc/applications/images-list.rst b/doc/applications/images-list.rst new file mode 100644 index 0000000..d1a7039 --- /dev/null +++ b/doc/applications/images-list.rst @@ -0,0 +1,25 @@ +List of existing container images +================================= + +Basic and runtime images +------------------------ + +.. csv-table:: + :file: images-list-basic.csv + :header-rows: 1 + +Common service images +--------------------- + +.. csv-table:: + :file: images-list-services.csv + :header-rows: 1 + +List of application images +-------------------------- + +All application images have the application user UID/GID 8080 and listen on internal port 8080 (HTTP). + +.. csv-table:: + :file: images-list-apps.csv + :header-rows: 1 diff --git a/doc/applications/index.rst b/doc/applications/index.rst new file mode 100644 index 0000000..642facb --- /dev/null +++ b/doc/applications/index.rst @@ -0,0 +1,14 @@ +Applications and containers +=========================== + +.. toctree:: + :maxdepth: 2 + + images-list + tech-knowledge + map-services + ckan + kanboard + sahana + sahana-configuration-report + seeddms diff --git a/doc/applications/kanboard.rst b/doc/applications/kanboard.rst new file mode 100644 index 0000000..4a54b4b --- /dev/null +++ b/doc/applications/kanboard.rst @@ -0,0 +1,121 @@ +Kanboard +======== + +Overview +-------- + +Kanboard is a Kanban project management tool written in PHP. It supports creation of projects and their population with tasks, provides Kanban boards with swimlanes, charts etc. It is extensile via plugins. + +Upstream URL: https://github.com/kanboard/kanboard + +Localization +------------ + +Kanboard is localized via PHP files containing associative arrays with original English string and the translation in the respective language. Every plugin has its own localization files. Due to this, we currently maintain forks or 4 repositories with plugins where the original maintainer decided to discontinue support. + +Plugins +------- + +Following list summarizes state of Kanboard plugins used or requested in our container as of 05/2020. + +BlueTeck/kanboard_plugin_overwrite_translation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/BlueTeck/kanboard_plugin_overwrite_translation + +Supplies translation strings via additional configuration file for other plugins which are missing or have incorrect translations. Not updated anymore, however the maintainer is active on GitHub. This plugin has initially been requested to be included in our installation, but due to its purpose, it's mostly useless as all translations were done in the respective plugin localization files. + +BlueTeck/kanboard_plugin_coverimage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/BlueTeck/kanboard_plugin_coverimage + +This plugin adds a cover image function to tasks on the board, and allows you to set a project image to use as a logo for projects. Development is active. + +BlueTeck/kanboard_plugin_metadata +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/BlueTeck/kanboard_plugin_metadata + +This plugin adds a basic GUI for Plugin Metadata. Not updated anymore, however the maintainer is active on GitHub. + +eSkiSo/Subtaskdate +^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/eSkiSo/Subtaskdate + +Adds a new due date field for subtasks, including events, API and search functions. Development is active. + +kanboard/plugin-budget +^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-budget +- Fork URL: https://github.com/trendspotter/kanboard-plugin-budget + +Allows to create budget lines, see expenses based on sub-task time tracking and manage user hourly rates. Repository has been forked. The original repository is archived. + +kanboard/plugin-calendar +^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-calendar + +Adds embedded calendar view for Kanboard. Development is active. + +kanboard/plugin-chat +^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-chat +- Fork URL: https://github.com/trendspotter/kanboard-plugin-chat + +Minimalist internal chat for Kanboard. Allows only one room for all users. Repository has been forked. The original repository is archived. + +kanboard/plugin-gantt +^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-gantt + +Adds Gantt charts for Kanboard. Development is active. + +kanboard/plugin-gravatar +^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-gravatar + +Enables Gravatar icons for Kanboard users. Repository is archived. There are no strings for translation, so it hasn't been forked. + +kanboard/plugin-registration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-registration + +Allows new user to sign up to Kanboard. Development is active. + +kanboard/plugin-sms-2fa +^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-sms-2fa +- Fork URL: https://github.com/trendspotter/kanboard-plugin-sms-2fa + +Allows to use text messages (SMS) instead of the default TOTP system (Time-based One-time Password Algorithm). Works with Twilio service. Repository has been forked. The original repository is archived. + +kanboard/plugin-task-board-date +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/kanboard/plugin-task-board-date + +Adds new date field for tasks to define the visibility on the board and dashboard. Repository is archived. There are no strings for translation, so it hasn't been forked. + +oliviermaridat/kanboard-milestone-plugin +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/oliviermaridat/kanboard-milestone-plugin + +Adds section for milestones to show their related tasks. Development is active. + +xavividal/kanboard-plugin-relationgraph +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- URL: https://github.com/xavividal/kanboard-plugin-relationgraph +- Fork URL: https://github.com/trendspotter/kanboard-plugin-relationgraph + +Shows relations between tasks using a graph library. Repository has been forked. The original repository is inactive. diff --git a/doc/applications/map-services.csv b/doc/applications/map-services.csv new file mode 100644 index 0000000..ba79512 --- /dev/null +++ b/doc/applications/map-services.csv @@ -0,0 +1,17 @@ +Application,Data sources,Map viewer,Configurable,Notes +CKAN,OSM (`Stamen `_),Leaflet,No,[1] +CrisisCleanup,Google Maps,Google Maps,No, +CTS,"OSM, `ArcGIS `_",Leaflet,No, +EcoGIS,,FreeGIS + OpenLayers 2,Probably,[2] +Odoo,Google Maps,Google Maps,No,[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 new file mode 100644 index 0000000..7f9cfa3 --- /dev/null +++ b/doc/applications/map-services.rst @@ -0,0 +1,12 @@ +Map services used in applications +================================= + +.. csv-table:: + :file: map-services.csv + :header-rows: 1 + +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. +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 new file mode 100644 index 0000000..177a503 --- /dev/null +++ b/doc/applications/sahana-configuration-report.rst @@ -0,0 +1,1490 @@ +Sahana Eden configuration and modules 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. + +The configuration has been tested on Sahana Eden version `56afb71 (2017-08-31 01:10:50) `_ using *default* template. + +Legend +------ +Each configuration directive is prepended with a tag representing its usability and readiness. + +========== ======= +Tag Meaning +========== ======= +**[O]** Works as advertised, does not require additional configuration +**[+]** Works with additional configuration explained in the description +**[!]** Does not work. Short analysis of the problem attached +**[N/A]** Untested or missing data +========== ======= + +Pre-Populate settings +--------------------- + +settings.base.guided_tour [!] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enables guided tours (hints about commonly used features) accessible from Help menu. Requires additional lines in *tasks.cfg* to populate with default *Welcome tour*. + +.. code-block:: text + + tour,config,guided_tour.csv,config.xsl + tour,details,guided_tour_details.csv,details.xsl + +| **Problem:** The tour does not show in the Help menu for unauthenticated user (as it is supposed to - see https://vimeo.com/67000529) and fails with multiple errors for authenticated user. + +Authentication settings +----------------------- + +settings.security.self_registration [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``True`` +| **Description:** Enables user self-registration via login form. + +settings.auth.registration_requires_verification [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enables requirement for e-mail verification while registering a new user. Requires additional settings for SMTP server via ``settings.mail.*`` directives. + +settings.auth.registration_requires_approval [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enables requirement for administrator approval while registering a new user. Requires additional settings for SMTP server and administrators e-mail address via ``settings.mail.*`` directives. + +settings.auth.registration_link_user_to [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Dictionary {String: String} +| **Default:** ``None`` in code, + +.. code-block:: python + + {"staff": T("Staff"), + "volunteer": T("Volunteer"), + "member": T("Member")} + +| commented in default *config.py* +| **Description:** Shows checkbox list on registration form and allows linking user to human resource type. The default keys ``staff``, ``volunteer`` and ``member`` are the only valid ones as they are hardcoded throughout the code (mostly in *s3aaa.py*). The linking only creates appropriate linked record between user and organisation but all specific values need to be populated manually. + +settings.auth.always_notify_approver [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``True`` +| **Description:** Enables notification to administrator when ``settings.auth.registration_requires_approval = False`` and a new user registers and validates their account. Requires additional settings for SMTP server and administrators e-mail address via ``settings.mail.*`` directives. + +settings.auth.opt_in_team_list [!] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** List [String] +| **Default:** ``[]`` +| **Description:** Adds user to defined team(s) if they checked the *Receive updates* checkbox in registration form. The teams have to be created manually or imported during pre-population phase. +| **Problem:** Enabling this option breaks user profile viewing on ``/eden/default/user/profile`` which fails with error 500 and stack trace + +.. code-block:: pytb + + Traceback (most recent call last): + File "/srv/sahana/gluon/restricted.py", line 227, in restricted + exec ccode in environment + File "/srv/sahana/applications/eden/controllers/default.py", line 1547, in + File "/srv/sahana/gluon/globals.py", line 417, in + self._caller = lambda f: f() + File "/srv/sahana/applications/eden/controllers/default.py", line 608, in user + form = auth.profile() + File "applications/eden/modules/s3/s3aaa.py", line 1566, in profile + ptable = s3db.pr_person + UnboundLocalError: local variable 's3db' referenced before assignment + +| The error can be corrected by initializing previously uninitialized variables via prepending line 1566 of *modules/s3/s3aaa.py* with + +.. code-block:: python + + db = current.db + s3db = current.s3db + +settings.auth.opt_in_default [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays the checkbox for *Receive updates* as checked by default. + +settings.auth.registration_requests_home_phone [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays a *Home Phone* input field in user registration form. Doesn't do full validation and doesn't enforce country code like the *Contact* tab does. + +settings.auth.registration_requests_mobile_phone [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays a *Mobile Phone* input field in user registration form. Doesn't do full validation and doesn't enforce country code like the *Contact* tab does. + +settings.auth.registration_mobile_phone_mandatory [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enforces the *Mobile Phone* field to be mandatory. + +settings.auth.registration_requests_organisation [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays an *Organisation* dropdown in user registration form. The organizations have to be created manually, imported during pre-population phase or created via ``settings.auth.registration_organisation_default``. + +settings.auth.registration_organisation_required [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enforces the *Organisation* dropdown to be mandatory. + +settings.auth.registration_organisation_hidden [!] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Hides the *Organisation* dropdown (using JavaScript only) unless the user enters a non-whitelisted domain (i.e. domain not listed for any existing group or organisation). +| **Problem:** The *Organisation* dropdown stays hidden at all times. Moreover there does not seem to be any way how to bind a domain name to organization other than manual insert into *auth_organisation* table (the *Website* field in organisation definition is not related to this setting). + +settings.auth.registration_organisation_default [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** String +| **Default:** ``None`` +| **Description:** Pre-populates the *Organisation* dropdown in user registration form with defined value. The organisation will be created automatically if it doesn't exist. + +settings.auth.registration_requests_organisation_group [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays a *Coalition* dropdown in user registration form. Requires additional CSV with the values and additional line in *tasks.cfg* to import it. + +.. code-block:: text + + org,group,org_group.csv,group.xsl + +| See the template *CRMT* and its files *modules/templates/CRMT/org_group.csv*, *modules/templates/CRMT/org_group_membership_status.csv* and *modules/templates/CRMT/org_group_person_status.csv* for more details. + +settings.auth.registration_organisation_group_required [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enforces the *Coalition* dropdown to be mandatory. + +settings.auth.registration_requests_site [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays a *Facility* dropdown in user registration form. + +settings.auth.admin_sees_organisation [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** The value of ``settings.auth.registration_requests_organisation`` (which is ``False`` by default) +| **Description:** Displays an *Organisation* dropdown in user administration even when the organisation is not requested during registration via ``settings.auth.registration_organisation_required = True``. + +settings.auth.show_utc_offset [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``True`` +| **Description:** Displays a *UTC offset* field (time zone) in user profile. Original comment in *config.py* suggests that the field should show up also in registration form but it doesn't. + +settings.auth.registration_roles [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Dictionary of Lists {Integer: [String]} +| **Default:** ``[]`` in code, ``{0: ["STAFF", "PROJECT_EDIT"]}`` commented in default *config.py* +| **Description:** Sets the default roles assigned to newly registered users. Dictionary key designates the realm that the list of roles applies to. ``0`` implies that the list is not realm restricted. List values are UUIDs stored in *auth_group* table. The roles have to exist before they can be referenced in this directive. + +settings.auth.org_admin_to_first [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Sets the organisation administrator role for the first user which registers for given organisation. The *Organisation* dropdown must be requested in registration form via ``settings.auth.registration_requests_organisation = True``. + +settings.auth.entity_role_manager [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enables entity role manager via *Roles* tab in *Staff* for organisation admins. Entity role manager allows for per-organization and per-module role management. + +settings.auth.realm_entity_types [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** List (String) +| **Default:** + +.. code-block:: python + + ("org_group", + "org_organisation", + "org_office", + "inv_warehouse", + "pr_group") + +| in code, ``("org_organisation",)`` commented in default *config.py* +| **Description:** Defines entity types to be used as realm entities for role management. Eg. user of one organisation won't have any rights in another organisation's records. + +settings.auth.role_modules [!] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Dictionary {string: string} +| **Default:** + +.. code-block:: python + + OrderedDict([ + ("staff", T("Staff")), + ("vol", T("Volunteers")), + ("member", T("Members")), + ("inv", T("Warehouses")), + ("asset", T("Assets")), + ("project", T("Projects")), + ("survey", T("Assessments")), + ("irs", T("Incidents")) + ]) + +| **Description:** Defines modules for entity role manager. +| **Problem:** User still has full access regardless of assigned roles. +| **TODO:** Check why everyone has admin roles to everything. + +settings.auth.access_levels [!] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Dictionary {string: string} +| **Default:** + +.. code-block:: python + + OrderedDict([ + ("reader", T("Reader")), + ("data_entry", T("Data Entry")), + ("editor", T("Editor")), + ("super", T("Super Editor")) + ]) + +| **Description:** Defines access levels for entity role manager. +| **Problem:** User still has full access regardless of assigned roles. +| **TODO:** Check why everyone has admin roles to everything. + +settings.auth.record_approval [N/A] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Enables record approval by administrator. +| **TODO:** Which one? superadmin / org admin / entity manager? + +settings.auth.record_approval_required_for [N/A] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** List (String) +| **Default:** ``[]`` in code, ``("org_organisation",)`` commented in default *config.py* +| **Description:** List of tables for which record approval is required. +| **TODO:** Seems that the approval is always automatically granted. Check why? + +settings.auth.registration_requests_image [O] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays a file selection button in registration form through which a new user is able to upload avatar image. + +settings.auth.registration_volunteer [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Redirects newly-registered users to *Volunteers* page to be able to add extra details. Requires disabled new user verification and approval via ``settings.auth.registration_requires_verification = False`` and ``settings.auth.registration_requires_approval = False``. + +settings.auth.terms_of_service [+] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +| **Type:** Boolean +| **Default:** ``False`` +| **Description:** Displays a *Terms of Service* link and agreement checkbox in registration form. The terms need to exist as separate HTML page *modules/templates/\