project publishing section redone

gisquick · Jul 12, 2017 · 5928915 · 5928915
1 parent 5dc1891
commit 5928915
Show file tree

Hide file tree

Showing 22 changed files with 3,804 additions and 334 deletions.
diff --git a/docs/img/docker-directory.svg b/docs/img/docker-directory.svg
diff --git a/docs/img/gisquick-plugin-base-layer.png b/docs/img/gisquick-plugin-base-layer.png
diff --git a/docs/img/gisquick-plugin-layers.png b/docs/img/gisquick-plugin-layers.png
diff --git a/docs/img/gisquick-plugin-project.png b/docs/img/gisquick-plugin-project.png
diff --git a/docs/img/gisquick-plugin-publish.png b/docs/img/gisquick-plugin-publish.png
diff --git a/docs/img/project-publishing-0.png b/docs/img/project-publishing-0.png
diff --git a/docs/img/project-publishing-1.png b/docs/img/project-publishing-1.png
diff --git a/docs/img/project-publishing-2.png b/docs/img/project-publishing-2.png
diff --git a/docs/img/project-publishing-3.png b/docs/img/project-publishing-3.png
diff --git a/docs/img/project-publishing-4.png b/docs/img/project-publishing-4.png
diff --git a/docs/img/project-publishing-5.png b/docs/img/project-publishing-5.png
diff --git a/docs/img/project-publishing-6.png b/docs/img/project-publishing-6.png
diff --git a/docs/img/publish-directory.svg b/docs/img/publish-directory.svg
diff --git a/docs/img/vagrant-directory.svg b/docs/img/vagrant-directory.svg
diff --git a/docs/index.rst b/docs/index.rst
@@ -32,7 +32,7 @@ insight into whole technology.
 
    installation/index
    project-publishing
-   environment-web
+   user-interface
    datasets   
    other
 

diff --git a/docs/installation-web.rst b/docs/installation-web.rst
diff --git a/docs/installation/docker.rst b/docs/installation/docker.rst
@@ -52,7 +52,9 @@ example is shown below.
          - ./_data/etc/letsencrypt/:/etc/letsencrypt/
        ports:
          - "443:443"
-        
+
+.. _docker-publish-dir:
+
 It is important to set up shared directories mounted by Docker images
 as volumes. *QGIS Server* requires setting up :file:`publish`
 directory which is used for published Gisquick projects (see line

diff --git a/docs/installation/user-management.rst b/docs/installation/user-management.rst
@@ -21,7 +21,14 @@ Afterwards on the server enter Django shell
 
    $ workon gisquick
    $ python $HOME/deploy/www/manage.py shell
+
+.. _vagrant-user:
 
+.. note:: Virtual server provided by Vagrant comes with predefined
+   ``vagrant`` user account. This account can be used for testing
+   purposes. Password for this account is the same as the name,
+   ie. *vagrant*.
+
 When running Gisquick by Docker containers, see :doc:`docker`, at
 first Django app docker container must be identified. The following
 command will also enter Django shell.

diff --git a/docs/installation/vagrant.rst b/docs/installation/vagrant.rst
@@ -48,6 +48,8 @@ To deploy virtual server called ``gisquick`` run:
    that, with next installation of server it can be faster because
    software packages will have not to be downloaded again.
 
+.. _vagrant-dev-dir:
+
 After succesfull deployment, new directories in source code tree are
 created:
 
@@ -114,6 +116,17 @@ Afterwards Gisquick can be accessed on https://localhost:8000.
  
 .. figure:: ../img/installation/vagrant-screen.png
 
+.. tip:: |tip| Use following command to run server tests from 
+   ``/vagrant/dev/django`` directory.
+
+   .. code:: sh
+
+      $ python ./manage.py test webgis.viewer.tests
+
+.. note:: |note| QGIS Mapserver is also forwarded to host machine on
+   port ``8090``.  Its logs can be found in ``/var/log/lighttpd``
+   directory.
+            
 Development services can be stopped from server terminal by ``tmux``
 command.
 
@@ -125,6 +138,7 @@ After logout, running virtual server can be shutdown by
 
 .. code-block:: sh
 
+   vagrant@gisquick:~$ logout
    $ vagrant halt
 
 Halted machine can be launched again by ``vagrant up`` command.
@@ -177,4 +191,3 @@ before starting :ref:`development services <vagrant-dev-services>`.
       $ /vagrant/utils/tmux-dev.sh
       $ cd /vagrant/clients
       $ gulp build-web
-
diff --git a/docs/other.rst b/docs/other.rst
@@ -39,9 +39,6 @@ See also related GitHub repositories:
 
 Gisquick QGIS plugin
   https://github.com/gislab-npo/gisquick-qgis-plugin, see :doc:`./installation/plugin`.
-Gisquick QGIS sample projets
-  https://github.com/gislab-npo/gisquick-sample-projects,
-  see :doc:`./datasets` section.
 Gisquick documentation
   https://github.com/gislab-npo/gisquick-doc
 

diff --git a/docs/project-publishing.rst b/docs/project-publishing.rst
@@ -32,9 +32,11 @@ Before publishing using Gisquick plugin, the project must be saved.
    to such data sources.
 
 Publishing QGIS project will be demostrated on :ref:`Prague sample
-project <dataset-prague>`. At first, sample :file:`prague.qgs` QGIS
-project will be open in QGIS Desktop. Before doing any changes we try
-to publish the project as it is.
+project <dataset-prague>` downloadable as as `zip file
+<http://training.gismentors.eu/geodata/gisquick/prague.tar.gz>`__. At
+first, sample :file:`prague.qgs` QGIS project will be open in QGIS
+Desktop. Before doing any changes we try to publish the project as it
+is.
 
 .. figure:: ./img/qgis-prague.png
 
@@ -44,29 +46,150 @@ Publication process is started by Gisquick QGIS plugin
 |plugin|. Plugin is designed as simple wizard which helps simplifying
 publishing process as much as possible.
 
-When ``Publish`` button is successfully pressed in GIS.lab QGIS plugin
-:ref:`dialog <gisquick-qgis-plugin-publish>`, 
-unique project file name with timestamp together with it's metafile are created.
-
-Then it is necessary to **copy** published QGIS project with all associated data 
-to ``vagrant`` directory that is located in ``gisquick`` source code.
+First page of the wizard allows defining basic settings for publishing:
+
+* **base layers**,
+* **overlay layers**, and
+* basic **project metadata**
+
+.. figure:: ./img/project-publishing-0.png
+
+By **base layers** are meant typically WMS layers provided by QGIS
+project. ``Base layer`` subpage also allows adding base layers provided by
+external services like OpenStreetMap, MapBox or Bing.
+
+.. important:: |imp| External base layers are available only when QGIS
+   project is using WGS84 Pseudo Mercator projection (EPSG:3857).
+
+Here also default base layer can be defined, see figure below.
+
+.. figure:: ./img/project-publishing-1.png
+
+In the second ``Layers`` subpage is controlled, simply by checkboxes,
+which map layers will be published. It's also possible to publish
+layer as hidden (ie. not shown in ``Overlay layers`` tab, see
+:doc:`user-interface`). Top-left checkbox ``Use cached`` controls
+usage of QGIS Server map cache. By default, overlay layers tiles are
+cached by QGIS server and re-used when possible.
+
+.. figure:: ./img/project-publishing-2.png
+
+The last ``Project`` subpage allows defining basic project metadata
+like title, extent, min/max scales, info message, access constraints,
+etc.
+
+.. figure:: ./img/project-publishing-3.png                        
+
+In the following page **topics** can be defined. By topic it's meant
+group of thematically-related overlay layers. Topics can be easily
+switched in ``Topics`` tab of Gisquick UI, see :doc:`user-interface`
+section. Layers which should be part of defined topic are simply
+checked. Topics can be added or removed by buttons localed in
+bottom-left part of the dialog. Each topic has defined short
+description (abstract) which is shown by Gisquick UI.
+
+.. figure:: ./img/project-publishing-4.png
+
+Last but one page showns read-only **configuration summary**. It's last
+chance to go back by ``Back`` button and change publication settings.
+
+.. figure:: ./img/project-publishing-5.png
+
+On the last page are displayed files which needs to transfered to the
+server providing Gisquick publication platform, see
+:doc:`installation/index` section. The result of publication proccess
+are two generated files: timestamped QGIS project (``.qgs``) and
+metafile (``.meta``). These files are data (see ``Data sources``) must
+be transfered to the publication server.
+
+.. figure:: ./img/project-publishing-6.png            
+
+.. _plugin-publish-directory:
+
+When ``Publish`` button is pressed, unique project file name with
+timestamp together with it's metafile are created. By default,
+timestamped files are created in the same directory as original QGIS
+project. The destination file can be changed by ``Change`` button. In
+this case data source files are also copied to the newly defined
+directory.
+
+Transfering project to publication server
+-----------------------------------------
+
+In this section is described finishing publication process,
+transfering published project to the publication server. Destination
+folder on the server can be different depending on installation
+process.
+
+When Gisquick is provided by **virtual server** controlled by Vagrant,
+see :doc:`installation/vagrant`, the generated timestamped files are
+copied to :file:`dev/publish` directory located in Gisquick source
+code tree from which virtual machine has been provisioned, see
+:ref:`directory layout <vagrant-dev-dir>`.
 
 .. figure:: img/vagrant-directory.svg
    :align: center
    :width: 450
 
-   Directory for QGIS projects going to be published.
+   Publish directory for virtual server controlled by Vagrant.
+
+In the case of **Docker-based** installation, see
+:doc:`installation/docker`, the publication directory is defined by
+:file:`docker-compose.yml` configuration file. In the presented
+:ref:`example <docker-publish-dir>` publication directory is located
+in Gisquick source tree :file:`docker/_data/publish`.
+
+.. figure:: img/docker-directory.svg
+   :align: center
+   :width: 450
 
-.. seealso:: |see| :ref:`Source code layout <source-code-layout>`
+   Publish directory provided by Docker containers.
 
-As the final step, open web browser and launch published project in Gisquick 
-interface by entering URL below.
-You will see welcome screen with possibility to enter credential but for now, 
-you can just ``Continue as guest``. 
+Projects in the *publish* directory are split into subdirectories
+corresponding registered users, see
+:doc:`./installation/user-management` section. In the case of virtual
+server it's possible to use predefined :ref:`vagrant user
+<vagrant-user>`.
 
+.. figure:: img/publish-directory.svg
+   :align: center
+   :width: 450
+
+   Publish directory provided by Docker containers.
+
+.. seealso:: ``|see| See also :ref:`Source code layout
+   <source-code-layout>`.
+
+.. important:: |imp| When user directory is not available in
+   :file:`publish` directory it's necessary to create it.
+
+Then it is necessary to **copy** published QGIS project (including
+timestamped files) with all associated data to user publish directory,
+eg. :file:`dev/publish/vagrant` or :file:`docker/_data/publish/user1`
+directory located in :file:`gisquick` source code tree. In our
+example, the project will be copied into
+:file:`dev/publish/vagrant/prague` directory.
+
+.. tip:: |tip| Instead of copying project files it is also possible to
+   define this output directory directly by :ref:`Gisquick plugin
+   <plugin-publish-directory>`. In this case the publish directory
+   must be accessible by clients via Network File System, FTP, or SSH.
+
+Published project is possible to access by URL formed by server name
+(https://localhost:8000 in the case of virtual server), user name,
+project directory and QGIS project file name, see URL below.
+
 .. code:: 
 
-   https://localhost:8000?PROJECT=vagrant/<project-directory-name>/<qgs-file-name>
+   https://localhost:8000?PROJECT=<user-name>/<project-directory-name>/<qgs-file-name>
+
+As the final step, open web browser and launch published project in
+Gisquick interface by entering URL, in our case
+eg. https://localhost:8000?PROJECT=vagrant/prague/prague.qgs.
+
+You will see welcome screen with possibility to enter credential
+(*vagrant/vagrant* or other used user account) but for now, you can
+just ``Continue as guest``.
 
 .. _gisquick-welcome:
 
@@ -85,23 +208,3 @@ And now there are no obstacles to enjoy your published project.
    :width: 750
 
    QGIS project published with Gisquick.
-
-.. seealso:: |see| See :ref:`Publish project on web <practice-gisquick-publishing>`
-   section with publishing QGIS projects from GIS.lab Desktop environment.
-
-Type ``tmux kill-session`` to destroy the given session, closing any windows 
-linked to it and no other sessions, and detaching all clients attached to it.
-Then use ``logout`` to log out from virtual 
-machine and ``vagrant halt`` to shut down the running machine Vagrant 
-is managing.
-
-.. tip:: |tip| Use following command to run server tests from 
-   ``/vagrant/dev/django`` directory.
-
-   .. code:: sh
-
-      $ python ./manage.py test webgis.viewer.tests
-
-.. note:: |note| QGIS Mapserver is also forwarded to host machine on port ``8090``.
-   Its logs can be found in ``/var/log/lighttpd`` directory.
-
diff --git a/docs/environment-web.rst → docs/user-interface.rst b/docs/environment-web.rst → docs/user-interface.rst