1. The Geopaparazzi Survey Server & Friends


The Geopaparazzi Survey Server (GSS) is a web application that allows geopaparazzi users to synchronize their project data with a central server.

Its companion is an Android app named Geopaparazzi Survey Server Sync (GSSS) available on google play. The app can connect to geopaparazzi projects and synchronize the data contained using the unique device ID to upload the data to the server.

A device, to be able to connect to the server, needs to be registered in the surveyor settings section of the server by an administrator user.

The applications are available as Free and Open Source software. The server is available under EPL v2.0, while the mobile app is available under GPL v3.0.

2. The server

2.1. Installation

The GSS server available as docker image from the docker hub. As such it works only on linux systems that have docker installed. Describing the installation of docker goes beyond this documentation. Many tutorials are available in the net to install docker.

01 hub
Figure 1. GSS on hub.docker.com.

To install the docker image just open a terminal and type in from shell:

docker pull moovida/gss:v2.12

This will download the server image and install it on your machine.

The installation process should reveal something similar to the following (the version number will most probably be different):

02 install
Figure 2. GSS installation process.

And once finished, the image should be visible with the command:

docker images

2.2. Preparing the data folder

To run GSS you can prepare the data folder for the server, which will contain the database (if it doesn’t exist, it is created from scratch), some styling components and optional mapsforge *.map files for local tiles generation.

You can just start with an empty folder, which will be filled with the bare minimum necessary to run GSS.

Let’s assume you are a heavy lifter and want to do things on your own, and that the data folder is named TESTGSS, then the folder structure needs contain at least the following:

|-- DATA    <-- folder
|   |-- images.png
|   `-- notes.png
`-- WORKSPACE    <-- folder

Where images.png and notes.png are the images that will be used in the map view to style geopaparazzi notes and media notes.

2.3. Run the server

To run the GSS server, it is necessary to define a few things:

  • the path to the data folder

  • the port that needs to be used

  • the docker image to use

Assuming we want to run the application on the data folder defined before and on port 8080, the command to run the application is:

docker run -v /media/hydrologis/Samsung_T3/TESTGSS:/home/basefolder -e JAVA_OPTS="-Xms1256m -Xmx4g -Dstage.globalfolder=/home/basefolder/" -p 8080:8080 moovida/gss:v2.12

Open your favorite browser and enter the url:


You should get the following login screen:

03 login
Figure 3. The GSS login screen.

This already means that you are ready to rumble!

You can login with:

  • user: god

  • password: god

Which already tells us that the user has quite some admin rights.

Once logged in, the dashboard view is shown.

2.4. GSS Views

The GSS views are organized as follows:

The upper toolbar features the menu button on the left, through which the side toolbar can be hidden. At the very right of the toolbar the currently logged user is shown.

The left toolbar contains buttons to access the available views:

  • Dashboard

  • Map View

  • Settings

    • Surveyors (admin mode)

    • Web Users (admin mode)

    • Map Chooser

  • Export

    • PDF

    • KMZ

    • Database (admin mode)

  • Project Data (admin mode)

  • Form Builder

  • Log View (admin mode)

  • About

  • Logout

2.4.1. The dashboard

The dashboard view shows a simple chart listing the amount of information for each device.

If no data are available, as in our inizial case, the folloing will be shown:

04 dashboard
Figure 4. The empty dashboard.

If instead data are available, the dashboard will give some information about the work in progress:

04 dashboard2
Figure 5. The dashboard.

2.4.2. The mapview

The mapview features the Surveyor list and a map panel.

The surveyor can be actived by selecting the checkbox in the table. Once the data of the surveyor are loaded, through the zoom button on top of the table it is possible to zoom to the surveyor’s data extent.

05 mapview
Figure 6. The mapview with the surveyors list.

If data are uploaded while on the map view, one can either reload the view by refreshing the page or:

  • using the first button to reload the data of the currently loaded surveyor

  • using the last button to reload all the available surveyors

The data can be queried by clicking on them. Simple information is shown as described below.

In the case of notes, the main note text, the elevation and the timestamp are shown. Note that or notes that have forms, the complex form is not visualized in the information box.

08 notes
Figure 7. Notes.

For GPS logs the name of the log and the start and end timestamp are shown.

09 logs
Figure 8. Gps Logs.

For media notes it is possible to visualize the images, by clicking on the image icon.

10 media
Figure 9. Media notes.

2.4.3. The Settings Views

Selecting the proper action from the settings menu it is possible to:

  • Configure surveyors. New devices that connect and upload are automatically added. The name of the surveyor by default is the id of the device. This can be changed by double-clicking on the surveyor.

12 surveyors
Figure 10. Surveyor configuration.
  • Create web users and groups. There are two levels of users: admins and normal users.

11 users
Figure 11. Web users configuration.
  • Configure background maps. Several map services can be added to the background maps that can then be selected in the mapview.

13 maps
Figure 12. The background maps configuration.
Many of the available map services need a license key to be accessed and/or have particular requirements to be used. Make sure that you have the rights to use the maps you select.

2.4.4. The Export Views

Selecting the proper action from the export menu it is possible to:

  • Export the data of one or more surveyors as PDF:

14 export pdf
Figure 13. The PDF export view
  • Export the data of one or more surveyors as KMZ:

15 export kmz
Figure 14. The KMZ export view
  • Export the current database. While it is best to connect to the online database through the port 9092, which is exposed, in some environments it might not be possible (ex. Heroku allows only one port). In this case it is possible to export the database by downloading it.

15 1 export db
Figure 15. The database export view

2.4.5. The Project Data View

In the project data view it is possible to upload datasets that can be downloaded by the mobiles app to allow geopaparazzi to access them.

The view is split into 3 columns, one for each supported datatype:

  • basemaps (mbtiles, mapsforge maps)

  • overlays (spatialite databases)

  • projects (geopaparazzi projects)

The user can simply drag the files in the lower area to upload the files.

23 dataview drag
Figure 16. The project data view

File types are placed in the right tables if recongized:

24 dataview
Figure 17. The different datatype tables

2.4.6. The Form Builder View

The form view is an interactive gui builder for geopaparazzi forms.

To better understand the description of its usage, some naming needs to be fixed:

  • tags: a tag is what we see as a complete file on geopaparazzi (speak tags.json). From version 5.6.2 on Geopaparazzi loads any file that ends with tags.json from the geopaparazzi folder, allowing tags to be kept separate.

  • section: a section is what in geopaparazzi is seen as a button in the add notes view.

  • form: a form is a tab of the geopaparazzi view

  • widget: it is the widget the user interacts with, ex. combobox or textfield

The naming is a bit confusing, but comes form the early days and is in the source code of geopaparazzi. So, in order to be able to always document things the same way, we have to follow these naming.

25 forms
Figure 18. The From Builder

After creating a tag with the add button, one can add a new section to the tag:

26 forms
Figure 19. The add section dialog.

Once the section is created the user can add forms to the section, which will load tabs for each one in the tab view.

To each of it widgets can be added:

27 forms
Figure 20. The add widget menu while adding a widget to a form tab.

The add widget dialogs prompt the user for a key and a label and other parameters depending on the type:

28 forms
Figure 21. The add text field widget
29 forms
Figure 22. The add combo widget, which can load from a textfile the combobox entries.
30 forms
Figure 23. The work in progress form view.

Once the user has finalized his tag entry, it is necessary to mark it visible in order for the mobile app to see it:

31 forms
Figure 24. The checkbox to mark the tag visible.

3. The mobile app, GSSS

The GSSS can be installed from the play store.

16 mobile install
Figure 25. GSSS on play store.

Once installed and launched it shows an empty view with the logo:

32 mobile
Figure 26. First start of GSSS.

In the side menu it is possible to access several features. The first 3 are the synchronization features:

  • Synchronization

  • Data Download

  • Forms Download

33 mobile menu
Figure 27. The main menu.

3.1. Settings

3.1.1. Checking the Device Id

The first thing to do is to check if the device has an own unique device id. If it has one, the following screen will be shown:

37 mobile id
Figure 28. The device id.

This is also the id that the server part uses as device identifier.

If no id is available, the user will be prompted to insert one manually.

3.1.2. Setting the server URL

To be able to connect to the GSS server, the URL of the server needs to be inserted.

38 mobile url
Figure 29. The upload URL of the server.

From the right side menu it is also possible to load a new geopaparazzi database and access some basic settings:

  1. the possibility to reset the connected database to be in a complete dirty state. After that the database will upload everything as if it never had done before.

  2. the possibility to reset the database to a clean state. After that no data are synchronized. Only new data surveyed in geopaparazzi will be uploaded again.

3.2. Synchronization

Once the app is configured, it is possible to load a project (first entry of the right side menu). A filechooser of dialog will open to select the database to synchronize. Once loaded the list of notes, gps log and media notes are shown in the tabbed view:

19 mobile load
Figure 30. The content of the database that can be synchronized.

To synchronize, the floating action button at the bottom right part can be used. It is possible to synchronize everything or just a part.

20 mobile syncfab
Figure 31. The action button that allows to upload notes, logs, media or everything.

Once the button is pushed, the app connects to the GSS server and sends the selected data to the server. At the end

40 mobile upload
Figure 32. The dialog of a successful sync.

3.3. Data Download

The Data download action opens an empty view and a referesh button. Once hit, the app will download the data available for the user to download:

35 mobile data
Figure 33. The data list downloaded from the server.

The icons show the different types of dataset.

One can download a dataset by tapping on the most left button with the cloud download icon.

3.4. Tags Download

The Forms download action opens an empty view and a referesh button. Once hit, the app will download the tags available for the user to download:

36 mobile tags
Figure 34. The tags list downloaded from the server.

3.5. Troubleshooting

If you experience issues or problems of any kind, you can use the send debug log button to send some debug information about the error to the developers. This will help them to solve the issue and create a new release.

22 send log
Figure 35. The send log button.

Note that the more information is added in the text view, the better it will be for the developers.

39 mobile log
Figure 36. The send log dialog