GeoServer

Description

GeoServer is a FOSS server allowing users to work with and visualize geospatial data. The software can publish data from any major spatial data source using open standards.

Installation and setup

GeoServer with Ubuntu 22.04 LTS (using Docker)

Please check the non-Docker installation first, it's a bit more complicated but gives you more control over your data.

Assuming you got your Ubuntu Server running, start the terminal and follow the steps

First we install Docker, if not already done so

1. sudo apt update
2. sudo apt upgrade
3. First add the repository to the latest community edition of Docker curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
4. Add the official repository echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
5. Install the dependencies sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release -y
6. Do an update again sudo apt update
7. Install the docker sudo apt-get install docker-ce docker-ce-cli containerd.io -y
8. Add the user of your choice to the Docker group sudo usermod -aG docker $USER

Now we add the geoserver container using the own data directory

1. sudo docker pull docker.osgeo.org/geoserver:2.23.4
2. docker run --mount type=bind,src=/MY/DATADIRECTORY,target=/opt/geoserver_data -it -p8081:8081 docker.osgeo.org/geoserver:2.23.4

Change /MY/DATADIRECTORY into whatever you wish and 8081 is the port you wish to use, feel free to appoint another port.

GeoServer on VirtualBox with Ubuntu 22.04 LTS (native - no Docker!)

The following is a step by step tutorial how to set up GeoServer on Ubuntu 22.04 LTS Server

The tutorial is based on the Tutorial by Hitesh Jethva with slight alterations for the versions as mentioned below (up-to-date at the moment of this writing) and focused on the MAPANAN project in the City of Baguio, Philippines to host Orthophotos by UAS in GeoTIFF format.

Software used for deployment, installation and setup

Version	Download link	Version used for this tutorial	Release date
Ubuntu Server	Ubuntu	22.04.4 LTS	16 Feb 2024
GeoServer	GeoServer	2.25.0	19 Mar 2024

Specifications of hardware

Hosting imagery doesn't really take that much resources, just to get it to work. I've got it running 150GB of high-res drone imagery on just 2 cores and 4GB RAM. Though speed is an issue and to get an acceptable responsiveness you should dedicate a bit more hardware.

Installation and setup for Ubuntu

Assuming you got your Ubuntu Server running, start the terminal and follow the following guidelines

1. sudo apt update
2. sudo apt upgrade
3. Verify if you got java already installed: java --version
4. sudo apt install openjdk-11-jdk -y - There's other versions feel free to suit your needs, GeoServer is tested to work with 8, 11 and 17 (11 more stable and tested)
5. wget https://sourceforge.net/projects/geoserver/files/GeoServer/2.25.0/geoserver-2.25.0-bin.zip Latest as of Mar 19 2025, or go for the older "stable" one at https://geoserver.org/release/stable/
6. sudo mkdir /usr/share/geoserver
7. sudo apt install unzip
8. sudo unzip -d /usr/share/geoserver/ geoserver-2.25.0-bin.zip
9. sudo groupadd geoserver Have a group to access the directory feel free to use a different name
10. sudo useradd -m -U -s /bin/false user1 - Replace "user1" with any other name of your choosing for the user(s) to access the shared folder
11. sudo usermod -aG geoserver user1
12. sudo usermod -aG geoserver user2
13. sudo chgrp -R geoserver /usr/share/geoserver
14. chmod -R g+rwX /usr/share/geoserver
15. sudo chown -R user1:geoserver /usr/share/geoserver
16. sudo vi /usr/lib/systemd/system/geoserver.service and enter the following into the document

[Unit]
Description=GeoServer Service
After=network.target

[Service]
Type=simple

User=geoserver
Group=geoserver

Environment="GEOSERVER_HOME=/usr/share/geoserver"

ExecStart=/usr/share/geoserver/bin/startup.sh
ExecStop=/usr/share/geoserver/bin/shutdown.sh

[Install]
WantedBy=multi-user.target

1. systemctl daemon-reload
2. systemctl enable --now geoserver
3. systemctl status geoserver - this will output if your service is loaded and active
4. you can now go to the website: http://yourip:8080/geoserver/ and it'll show you the main login
5. default username/password is admin/geoserver - on the left side you can go to Security->Users, Groups, Roles->Users/Groups->admin now you can change your administrator username and password and at this point your done setting up the GeoServer.Proceed with configuration

Data Directory

It is advisable to change the default data directory outside of the root directory of the Geoserver. It eases updating the Geoserver to newer releases.

1. Please edit the service file /usr/lib/systemd/system/geoserver.service and add the environment variable Environment="GEOSERVER_DATA_DIR=/usr/share/geoserver_data" under the [Service]
2. Alternative, only if you can't set the environment variable through the service or don't want to run it as a service: vi .bash_profile or vi .bashrc and add the line export GEOSERVER_DATA_DIR=/usr/share/geoserver_data
3. Last resort, if you find yourself having problems to edit the environment variable you may edit the file vi /usr/share/geoserver/webapps/geoserver/WEB-INF/web.xml

and change the following

<!--
   <context-param>
      <param-name>GEOSERVER_DATA_DIR</param-name>
      <param-value>C:\eclipse\workspace\geoserver_trunk\cite\confCiteWFSPostGIS</param-value>
   </context-param>
-->

into

   <context-param>
      <param-name>GEOSERVER_DATA_DIR</param-name>
      <param-value>/anywhere_outside_root_dir</param-value>
   </context-param>

Plugins / Extensions

Installing plugins is very simple and straight-forward, but for the sake of completeness I'll add an example of the authentication module. Ensure versions match!

1. Go to https://build.geoserver.org/geoserver/ and browse to the version of your Geoserver
2. Under "ext-latest" you'll find the updated plugin versions for your Geoserver version
3. Use the wget command to download the zip wget https://build.geoserver.org/geoserver/2.25.x/ext-latest/https://build.geoserver.org/geoserver/2.25.x/ext-latest/geoserver-2.25-SNAPSHOT-authkey-plugin.zip
4. Unzip wherever you wish unzip -d authkey -o geoserver-2.25-SNAPSHOT-authkey-plugin.zip the -o ensures you overwrite any older unzip files in case you're upgrading
5. Now look inside the unzip directory for *.jar files and copy all of them to the plugin directory cp authkey/gs-authkey-2.25-SNAPSHOT.jar /usr/share/geoserver/webapps/geoserver/WEB-INF/lib/gs-authkey-2.25-SNAPSHOT.jar and do this for all .jar files
6. restart the Geoserver and your plugins are up and running
7. take note, plugins have documentation, our example plugin https://docs.geoserver.org/stable/en/user/extensions/authkey/index.html

Updating and upgrading your installation

If you have your data directory outside of the root geoserver folder this is pretty straight forward.

You should update twice a year to keep up with vulnerabilities

1. Make a backup folder of your existing data directory cp -r /usr/share/data_dir /usr/share/data_dir_bck
2. Go to the Geoserver Status page and there to the Modules tab and take note of the plugins/extensions you have installed
3. Stop the service systemctl stop geoserver
4. Delete the existing geoserver root folder rm -r /usr/share/geoserver
5. Proceed now with the wget and unzip for the newer version to the same geoserver directory
   1. Download maintenance to update existing release http://geoserver.org/release/maintain
   2. Download stable to upgrade to a new release http://geoserver.org/release/stable
6. Do the same wget and unzip and copy to the proper directory for plugins/extensions
7. Now you can start the Geoserver systemctl start geoserver
8. After restarting the newest version should automatically update the data directory to be compatible with the newest version and everything should be up and running

note if something goes wrong, this can happen if you have skipped many updates/upgrades and do many at once, use the backup directory and go back to your original version and try to update incrementally

Troubleshooting

1. If you on Ubuntu Server run into 403 or 115 errors, these are server errors! Quite often from local servers which are IP-restrictive.
   • Open your sources.list with an editorsudo nano /etc/apt/sources.list
   • at this point find all references to local servers i.e. http://ph.archive.ubuntu.com/ubuntu and replace with http://archive.ubuntu.com/ubuntu
2. If you run into errors "The method 'ftp' is unsupported and disabled by default." run the following command
   • echo 'Dir::Bin::Methods::ftp "ftp";' | sudo tee -a /etc/apt/apt.conf.d/99local-ftp
3. If you run into "couldn't open data connection" errors for some downloads during sudo apt-get install xxxx while others download just fine, do the following:
   • sudo apt-get update --fix-missing
   • sudo apt-get install xxxx
   • repeat these steps until you got them all, in some cases you may have to repeat this many times but you'll get them all eventually.
4. Geoserver has some rights/ownership specifics. The folder with the drone images should be properly set:
   • sudo chown -R username:groupname foldername
   • sudo chmod -R 770 foldername
5. To Remove/change Java and install another version: https://askubuntu.com/questions/84483/how-to-completely-uninstall-java
6. Removing old service (if needed for upgrading process)

   systemctl cat [servicename] # info on the files for this servicename
   systemctl stop [servicename]
   systemctl disable [servicename]
   rm /etc/systemd/system/[servicename]
   rm /etc/systemd/system/[servicename] # and symlinks that might be related
   rm /usr/lib/systemd/system/[servicename] 
   rm /usr/lib/systemd/system/[servicename] # and symlinks that might be related
   systemctl daemon-reload
   systemctl reset-failed
   

Configuration

	First go to Workspaces
	Create a new workspace
	Click on the newly created workspace and set WMTS, WMS and if required enable the settings and fill out the data as you see fit
	Next add new stores as you see fit. I arranged them per quarter of the year so newer orthographic images automatically overwrite older
	Select from the list of options the ImageMosaic under the Raster Data Sources

Configuration of authentication module

In the official documentation there's a lot of technical additional information you don't need to know and might be confusing for Linux-novices who just want things to be up&running without understanding the technical details. So we focus here simply on the practical steps to get your stuff up&running so you can use the data hosted on the server to be compatible with Vespucci for your mapping activities to OSM.

1. On the Geoserver web interface, under "About & Status" please click on "Server Status" and then the tab "Modules" to verify that you have "Authkey Extension" available and enabled
2. Under "Security" click on "Authentication" and then under "Authentication Filters" you click on "Add new"
3. The basic functionality can be provided with the settings as in the following image

   

   Geoserver Authentication Module Extension Basic Settings

4. Click on "Synchronize user/group service" to ensure you generated the property file used for the UUID generation of the users
5. You now generated a new file "authkeys.properties" which on our example setup can be found at "/usr/share/geoserver_data_dir/security/usergroup/default"
6. Open this file in a text editor of your choice and notice the format is "authkey=username"
7. The {authkey} values you see here are what you use to identify to the authkey at the end of the URL-string for the WMS layers in for instance Vespucci
8. After saving your settings, click on "default" under the "Filter Chains"
9. At the bottom under "Available" you now see the option "authkey" has been added, move it to the top of "Selected" field
10. Click on "Close" to get back to the "Authentication" page and at the bottom click on "Save"

Please note that this is just a basic example which serves us on internal network through HTTP, you can configure Authentication Module in many ways to support this method including external online methods. If you do this exposed to the internet, then ensure you have https up and running and restrict this authorization method to HTTPS only!

Examples for URL-string to access WMS layers through the authorization module

http://192.168.90.44:8083/geoserver/ows?service=WMS&version=1.3.0&request=GetCapabilities&authkey=00000000-0000-0000-0000-000000000000
http://192.168.90.44:8083/geoserver/ows?FORMAT=image/png&TRANSPARENT=TRUE&VERSION=1.3.0&SERVICE=WMS&REQUEST=GetMap&LAYERS=ort:mapanan2024&STYLES=&SRS=EPSG:3857&WIDTH={width}&HEIGHT={height}&BBOX={bbox}&authkey=00000000-0000-0000-0000-000000000000

Please note that the last entry is what you would use in "Custom layers" for Vespucci. In our case the following image shows the full settings for our setup having <10cm accurately georeferenced orthophotomosaic served for mapping purposes.

Vespucci custom layer WMS with authkey

Maintenance of Stores for Mosaic Imagery

The web interface doesn't provide an automated update for stores. Copying a new orthographic image to the directory of a given workspace won't thus automatically update. One can manually wipe clean the corresponding files in the directory or wipe out the caching and then manually re-scan the directory. This is time consuming and prone to errors.

Setting up a cron job for this is the easiest way, it may need root permission

1. enter in the shell to work as root

   sudo -i
   

2. create a file for instance in the root home folder

   vi updategeoserver
   

3. Enter the code below into that file so its command can be executed by root

#!/bin/bash curl -v -u admin:geoserver -XPOST -H "Content-type: text/plain" -d "file:///path/to/the/mosaic/folder" "http://localhost:8080/geoserver/rest/workspaces/<workspace_name>/coveragestores/<store_name>/external.imagemosaic"

<workspace_name> replace this with the workspace "Name" listed under "Basic Info" in the "Edit Workspace" web interface. <store_name> replace this with the "Data Source Name" listed under "Basic Store Info" in the "Edit Raster Data Source" web interface for the corresponding Store. example: curl -v -u admin:geoserver -XPOST -H "Content-type: text/plain" -d "file:///var/snap/nextcloud/common/nextcloud/data/HikeAndMap/files/Survey/UAV/2_OUTPUT/orthophoto/2023" "http://localhost:8080/geoserver/rest/workspaces/baguio_ortho/coveragestores/ortho_2023/external.imagemosaic" Clearly keep in mind to replace the default admin:geoserver with the username:password of your choosing

The cron job itself the easiest, assuming still logged on as root

1. Execute the follow command to enter the cron job file for root

   crontab -e
   

2. The following line will update the Geoserver store for that specific directory once per hour

   */60 * * * * ./updategeoserver
   

At this point your Geoserver for that specific store/workspace will update automatically once an hour.

To clean a geoserver folder one can just create a script file analog to the update command and wipe out the geoserver generated files

1. enter in the shell to work as root

   sudo -i
   

2. create a file for instance in the root home folder

   vi cleangeoserver
   

3. Enter the code below into that file so its command can be executed by root

#!/bin/bash rm ../folder/*.dbf rm ../folder/*.fix rm ../folder/*.prj rm ../folder/*.properties rm ../folder/*.qix rm ../folder/*.shp rm ../folder/*.shx rm ../folder/sample_image.dat

* example: ../../var/snap/nextcloud/common/nextcloud/data/HikeAndMap/files/Survey/UAV/2_OUTPUT/orthophoto/2024/2024.dbf

Linux commands

getent group group_name	Users in a group
cat /etc/group	Lists all groups
cat /etc/passwd	Lists all users
userdel -r usernamed	Deletes a user from Linux '-r' deletes $HOME folder
ls -ld directory	Get permissions of directory
sudo -i	Elevate to root
docker container ls -a	Show all containers
docker container rm ID	Remove container with ID
systemctl list-unit-files | grep enabled	find all enabled services using systemctl
systemctl restart geoserver.service	restart the service

Important linux locations

/var/snap/nextcloud/common/nextcloud/data	Data directory of NextCloud using Snap installation
/usr/share/geoserver/webapps/geoserver/WEB-INF/classes/org/geoserver/web/img/logo.png	This is the location to overwrite the Geoserver icon in the upper left corner with your own
/usr/share/geoserver/start.ini	File that holds startup data like port number
/usr/share/geoserver/webapps/geoserver/WEB-INF/lib	Plugins directory

Tile optimizations and practical experience

The red polygon on the left is the size of the original orthographic imagery hosted on Geoserver to be used in JOSM for mapping purposes on OpenStreetMap. It's rather slow in the rendering in JOSM on higher zoom levels. The right side shows we cut the single large file into 12 smaller pieces to be hosted on the Geoserver, now the rendering in JOSM is significantly improved and improves the mapping experience.

Hosting the high resolution orthographic images comes with a caveat, namely the sheer amount of data results in huge file sizes. In JOSM, QGIS and similar software for both the mapper and for the data consumer it's quite slow in the loading the data and the delays the mapper gets on his end using JOSM are frustrating to staff and students using the hosted imagery for mapping activities as well as data consumer activities using OpenStreetMap in conjunction with orthographic imagery in QGIS.

We found by trial and error that smaller individual tiles hosted instead of large single files speeds up this process especially when zooming-in and -out in JOSM on higher zoom levels.

Therefore we use predefined squared cut-lines to split the large single survey orthographic images into smaller parts.

GDAL, splitting orthographic images

placeholder