Documentation update for Sahana local development, closes #337

doc/applications/sahana.rst

@@ -26,3 +26,67 @@ Localization
 Czech localization for Sahana Eden is currently not a part of upstream code. It is currently held in SpotterVM repository and there are currently no plans to submit a pull request with the translation.
 
 The localization is done via translation export function of Sahana Eden found in the administration menu. The exported CSV or XLS file is then manually translated and fed back to ``sahana-lang-convert.py`` helper script which generated the appropriate python dictionary file used as translation. Some strings are not output by the translation function and are either hardcoded or composed, so there is also ``sahana-lang-compare.py`` helper script which traverses installed Sahana Eden instance and tries to locate and supply all missing strings from the previous translation file. Both helper scripts are also contained in the SpotterVM repository.
+
+Local development
+-----------------
+
+Since Sahana Eden is the crown jewel of the whole environment and unfortunately also the most buggy application, it may be needed to work on some development tasks and bugfixes outsite of the VM environment. Following are a few tips to important tasks and gotchas you may encounter.
+
+To enable debug mode for Sahana, set ``settings.base.debug = True`` in ``applications/eden/models/000_config.py``.
+
+Database migration
+^^^^^^^^^^^^^^^^^^
+
+New commits (both upstream and local) can require a modification of database structure. If this is not done, Sahana may report internal server errors or corrupt the database. Migration to the up-to-date schema version can be achieved via following steps.
+
+.. code-block:: bash
+
+    # Change directory to web2py root
+    cd /srv/web2py
+
+    # Allow database migration (normally denied in prod)
+    sed -i 's/settings.base.migrate = False/settings.base.migrate = True/g' applications/eden/models/000_config.py
+
+    # Remove old cached bytecode
+    rm -rf applications/eden/compiled
+
+    # Run the migration task
+    python web2py.py -S eden -M -R applications/eden/static/scripts/tools/noop.py
+
+    # Deny database migration (improves performance)
+    sed -i 's/settings.base.migrate = True/settings.base.migrate = False/g' applications/eden/models/000_config.py
+
+    # Precompile fresh bytecode
+    python web2py.py -S eden -M -R applications/eden/static/scripts/tools/compile.py
+
+Factory reset
+^^^^^^^^^^^^^
+
+In case you'd like to wipe all data and restore your Sahana instance to pre-installation phase, stop all Sahana (uWSGI) processes and run the following.
+
+.. code-block:: bash
+
+    # Drop and recreate database
+    cat <<EOF | sudo -u postgres psql
+    DROP DATABASE sahana
+    REVOKE ALL ON DATABASE sahana FROM public;
+    ALTER DATABASE sahana OWNER TO sahana;
+    \c sahana;
+    CREATE EXTENSION postgis;
+    GRANT ALL ON geometry_columns TO sahana;
+    GRANT ALL ON spatial_ref_sys TO sahana;
+    EOF
+
+    # Change directory to web2py root
+    cd /srv/web2py
+
+    # Wipe file caches
+    rm -rf applications/eden/compiled
+    rm -rf applications/eden/databases/*
+    rm -rf applications/eden/uploads/*
+    rm -rf applications/eden/errors/*
+    rm -f applications/eden/config/0000_update_check.py
+
+    # Allow database migration and prepopulation
+    sed -i 's/settings.base.migrate = True/settings.base.migrate = False/' applications/eden/models/000_config.py
+    sed -i 's/#settings.base.prepopulate = 0/settings.base.prepopulate = 0/' applications/eden/models/000_config.py

doc/toolchain/virtual-machine-creation.rst

@@ -66,8 +66,10 @@ There are 3 distinct packaging systems.
 
 1. Just a plain *tar.gz* for basic OS setup used by ``vm.sh`` installation script.
 2. `Abuild <abuild.html>`_ for the native Alpine linux packages (APK) used for ACME client and VMMgr packaging.
-3. `SPOC <spoc.html>`_ for SPOC container building and packaging.
+3. `SPOC <spoc-overview.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.
 
-One the setup is complete, build and packaging can be done manually on per-container basis or a full build of all components can be run via ``build-all.sh`` script. The full build process takes considerable amount of time, so it is advised to have a persistent build VM and rebuild only updated packages.
+Once the setup is complete, build and packaging can be done manually on per-container basis or a full build of all components can be run via ``build-all.sh`` script. The full build process takes considerable amount of time, so it is advised to have a persistent build VM and rebuild only updated packages.
+
+The ``build-all.sh`` script, resp. most of the build tools it calls, check if the packages they're building have already been built. When a failure occurs and the whole build chain is stopped, rerunning the ``build-all.sh`` will pick up where it left off with very little overhead and will rebuild only the items which have failed, haven't been built yet or have been updated since the last run.