add to documentation: how to register apps and documentation to the admin sidebar

[mojodna]

As of the upcoming 0.8.0 release of POSM (via posm/[email protected]), the admin sidebar is customizable.

OpenDroneMap and Imagery links will only appear if those services are available (it probes /projects and /imagery for valid responses).

External applications (OpenMapKit, Field Papers, etc) and documentation (POSM Guide, About OMK, etc.) are driven by config.json

To manually add (or remove) applications or documentation, edit /opt/posm-www/config.json on a POSM install.

config.json is updated as part of the deployment process, so if additional components are made available, they can self-register links using shell fragments similar to:

  # load the existing list of apps
  apps=$(jq .apps /opt/posm-www/config.json)
  # create a list with existing apps and new apps (move $apps below to prepend new apps)
  # jq's unique function is used to avoid creating multiple copies of an app
  # "icon" corresponds to Blueprint class names: http://blueprintjs.com/docs/#icons
  # ${posm_fqdn} corresponds to the matching key in the settings file (kickstart/etc/settings) and /etc/posm.json
  new_apps=$(cat << EOF | jq -s '.[0] + .[1] | unique'
$apps
[
  {
    "name": "ODM GCPs",
    "icon": "layout-skew-grid",
    "url": "//${posm_fqdn}/posm-gcpi/",
    "description": "OpenDroneMap Ground Control Points"
  }
]
EOF
)

  # do the same thing for docs
  # if no docs need to be added, omit this and the docs key below
  docs=$(jq .docs /opt/posm-www/config.json)
  new_docs=$(cat << EOF | jq -s '.[0] + .[1] | unique'
$docs
[
  {
    "name": "POSM Guide",
    "icon": "book",
    "url": "//${posm_fqdn}/guide/"
  },
  {
    "name": "About OMK",
    "icon": "book",
    "url": "//${posm_fqdn}/openmapkit-website/",
    "description": "About OpenMapKit"
  }
]
EOF
)

  # load the existing config
  config=$(jq . /opt/posm-www/config.json)
  # replace apps and docs keys and write it out
  cat << EOF | jq -s '.[0] * .[1]' > /opt/posm-www/config.json
$config
{
  "apps": $new_apps,
  "docs": $new_docs
}
EOF

(See also https://github.com/posm/posm-build/blob/2bc1182bc5691060a11d72de77b9cffb6ef10990/kickstart/scripts/nginx-deploy.sh#L26-L66)