deegree 3.6.14 on AWS User Guide

Overview

This guide covers launching and using the deegree 3.6.14 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg GIS, health and research applications listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

deegree is an open source framework of OGC web services, an OSGeo project. It publishes spatial data as Web Map Service (WMS), Web Feature Service (WFS) and Web Map Tile Service (WMTS) endpoints that desktop GIS (QGIS, ArcGIS), web map clients (OpenLayers, Leaflet) and other OGC software connect to. It is configured through workspaces: directories of XML files that describe data stores (shapefiles, GeoPackage, PostGIS, rasters), layers, styles and services. A browser-based services console and a REST API manage the workspaces.

The cloudimg image is a hardened, ready-to-use deegree server:

• It answers real requests on the first boot. deegree's own Utah demo workspace is installed and active: municipalities, counties, roads, rivers, lakes and contours as feature layers, plus elevation and orthophoto rasters, all on the instance. The one layer in it that cascaded a remote WMS has been removed, so no request depends on a third-party service, and service limits are set (WMS maps up to 4096 x 4096 pixels and 16 layers, WFS responses up to 10000 features).
• nginx in front, deegree behind it. nginx is the only public listener (ports 80 and 443) and serves the OGC endpoints (/deegree-webservices/services/...) and a landing page, nothing else. deegree runs in Apache Tomcat on 127.0.0.1:8080, the loopback address only (no shutdown port, no AJP), and the instance itself refuses 8080, 8005 and 8009 from the network.
• HTTPS from the first boot, with a certificate generated on your instance (an end-entity certificate, not a certificate authority), TLS 1.2 and 1.3 only. Port 80 redirects to HTTPS. The instance's name is set from its own address at first boot and is the address the capabilities documents advertise; requests for any other host name are dropped. You can change it to your own domain.
• The administration surface is not public. The services console, the /config REST API and /resources answer 404 on port 443. You reach them through an SSH tunnel. First boot generates a console password (deegree stores only its crypt SHA-256 hash) and a REST API key, both unique to your instance, in files only root and deegree can read; deegree refuses to start without them, so it never runs with an open console or a default key. The image runs 3.6.14, the release that fixes the critical unauthenticated workspace upload of 3.5.0 to 3.6.13 (GHSA-3rr8-fqm7-63hf), and every build proves that uploads without this instance's key are refused and that OGC requests carrying XML external entities do not read local files or reach other hosts.
• An egress backstop. deegree fetches remote styles, XLinks and schemas when a request names them, so the tomcat account (deegree) and the www-data account (nginx) are refused, by iptables and by systemd, every connection to the EC2 metadata service, private and carrier-grade NAT addresses, link-local and reserved ranges, and this instance's own VPC ranges, which the instance reads from EC2 metadata at every boot. The backstop is fail closed: if the VPC ranges cannot be read, deegree does not start. Public OGC services stay reachable. Step 9 shows how to allow a database in your VPC on purpose.
• An unprivileged service. Tomcat and deegree run as the tomcat account, which has no shell, no password and no sudo rights, under systemd with NoNewPrivileges, a read-only operating system (ProtectSystem=strict), no capabilities and core dumps off.
• Patched, pinned components. Apache Tomcat 10.1.61 comes from the upstream release, checked against its published SHA-512 hash (the Ubuntu Tomcat packages are in the unsupported universe archive). The deegree WAR and the Utah workspace are checked by SHA-256. OpenJDK 17, nginx and every other package are from the Ubuntu 24.04 main archive, on a fully patched Ubuntu 24.04 LTS with unattended security upgrades on.

What is on the image: deegree webservices 3.6.14 on Apache Tomcat 10.1.61 under OpenJDK 17, the Utah demo workspace, nginx and iptables from Ubuntu 24.04, cloud-init and the AWS Systems Manager agent.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet.
• A security group that allows TCP 22 (SSH) and TCP 443 (the OGC services) and TCP 80 (redirects to HTTPS) from the networks your users and GIS clients are on. Do not open 8080: Tomcat listens on the loopback address only and the console is reached through SSH.
• IMDSv2 enabled (the default for this AMI). The instance reads its own VPC ranges from the metadata service at every boot; with the metadata service switched off, deegree does not start (see Step 9).
• For production, a DNS name you control (for example deegree.example.com) and, ideally, a certificate from a certificate authority. Until then the instance uses its public IP address with its own self-signed certificate.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick deegree 3.6.14 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large (or larger for big rasters or many concurrent map requests), your key pair, and a security group as above. Workspaces and their data live under /var/lib/deegree/workspaces on the root volume, so size the root volume for the data you will load.

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --image-id <ami-id-from-the-listing> --instance-type m5.large \
  --key-name <your-key-pair> --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=deegree}]'

First boot takes about a minute after the instance is running: it generates the console password, the API key and the certificate, then deegree starts and loads the workspace. First boot uses the instance's public IP address as its name (or its private address if it has no public one), and also serves its EC2 public DNS name and its private address.

Step 2: Connect to your instance

Operating system	SSH user
Ubuntu 24.04	ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

The login message shows the OGC address and where the credentials are.

Step 3: Check the services

systemctl is-active cloudimg-deegree-vpc-cidrs cloudimg-deegree-egress deegree nginx

active
active
active
active

(127.0.0.53 and 127.0.0.54 are Ubuntu's local DNS resolver. deegree-firstboot runs once, on the first boot, and shows inactive on every later boot.)

Only SSH, HTTP and HTTPS are public; Tomcat listens on the loopback address:

sudo ss -Htln | awk '{print $4}' | sort -u

0.0.0.0:22
0.0.0.0:443
0.0.0.0:80
127.0.0.1:8080
127.0.0.53%lo:53
127.0.0.54:53
[::]:22
[::]:443
[::]:80

Step 4: Read the address and the certificate fingerprint

Everything first boot generated is in /root/deegree-credentials.txt (root only). The OGC address, the host name and the certificate's SHA-256 fingerprint:

sudo grep -E '^DEEGREE_(OWS_URL|HOST|TLS_SHA256)=' /root/deegree-credentials.txt

DEEGREE_OWS_URL=https://203.0.113.10/deegree-webservices/services
DEEGREE_HOST=203.0.113.10
DEEGREE_TLS_SHA256=3E:09:D1:00:B7:E2:8B:75:92:EA:0A:DF:C9:E7:F3:9E:0C:23:98:A7:D4:A5:83:89:D3:B8:81:B0:6D:DD:33:C0

The same file holds DEEGREE_CONSOLE_PASSWORD and DEEGREE_REST_API_KEY; read them with sudo cat /root/deegree-credentials.txt when you need them, and keep them out of tickets and chat. The certificate is self-signed for this instance: when a browser or GIS client asks you to trust it, compare its SHA-256 fingerprint with DEEGREE_TLS_SHA256.

Step 5: Use the OGC services

Open https://<DEEGREE_HOST>/ (for example https://203.0.113.10/) in a browser for the landing page, which lists the service addresses:

In QGIS, add a WMS/WMTS connection with the URL <DEEGREE_OWS_URL>/wms (or /wmts) and a WFS connection with <DEEGREE_OWS_URL>/wfs. From the instance itself, the commands below pin each request to this instance's certificate. The certificate directory is root only, so first copy the (public) certificate to your home directory:

sudo cat /etc/ssl/deegree/deegree.crt > ~/deegree.crt

The WMS capabilities and the first of the layer names it offers (the names you use in a GetMap):

curl -s --cacert ~/deegree.crt --resolve <DEEGREE_HOST>:443:127.0.0.1 \
  "https://<DEEGREE_HOST>/deegree-webservices/services/wms?service=WMS&version=1.3.0&request=GetCapabilities" \
  | grep -o '<Name>[a-z][^<]*</Name>' | sed 's/<[^>]*>//g' | grep -vx default | sort -u | head -12

administration
airports
cities
counties
countyboundaries
countynames
dominantvegetation
elevationcontours
energyresources
groundwater
lakes
municipalities

A map of Utah's counties, roads and rivers as a PNG:

curl -s --cacert ~/deegree.crt --resolve <DEEGREE_HOST>:443:127.0.0.1 -o /tmp/utah.png \
  "https://<DEEGREE_HOST>/deegree-webservices/services/wms?service=WMS&version=1.3.0&request=GetMap&layers=counties,roads,rivers&styles=&crs=EPSG:4326&bbox=36.9,-114.1,42.1,-108.9&width=1024&height=820&format=image/png"
file -b /tmp/utah.png

PNG image data, 1024 x 820, 8-bit/color RGB, non-interlaced

The WFS feature types, and five features of one of them as GML:

curl -s --cacert ~/deegree.crt --resolve <DEEGREE_HOST>:443:127.0.0.1 \
  "https://<DEEGREE_HOST>/deegree-webservices/services/wfs?service=WFS&version=2.0.0&request=GetCapabilities" \
  | grep -o '<Name xmlns:app="[^"]*">[^<]*</Name>' | sed 's/<[^>]*>//g' | head -8

app:Airports
app:DominantVegetation
app:SGID024_Municipalities2004_edited
app:SGID024_Springs
app:SGID100_CountyBoundaries_edited
app:SGID100_LakesDLG100
app:SGID100_RailroadsDLG100
app:SGID100_RoadsDLG100

curl -s --cacert ~/deegree.crt --resolve <DEEGREE_HOST>:443:127.0.0.1 \
  "https://<DEEGREE_HOST>/deegree-webservices/services/wfs?service=WFS&version=2.0.0&request=GetFeature&typeNames=app:Airports&count=5" \
  | grep -o '<wfs:member' | wc -l

5

A WMTS tile of the Provo orthophoto at its coarsest zoom level (the tile matrix identifiers of this tile matrix set are map scales):

curl -s --cacert ~/deegree.crt --resolve <DEEGREE_HOST>:443:127.0.0.1 -o /tmp/tile.png \
  "https://<DEEGREE_HOST>/deegree-webservices/services/wmts?service=WMTS&version=1.0.0&request=GetTile&layer=utah_ortho&style=default&tilematrixset=Satellite_Provo&tilematrix=57142.857142857145&tilerow=0&tilecol=0&format=image/png"
file -b /tmp/tile.png

PNG image data, 128 x 128, 8-bit/color RGBA, non-interlaced

The administration paths are not served publicly:

for p in / /deegree-webservices/ /deegree-webservices/config/listworkspaces /deegree-webservices/resources/; do
  curl -s --cacert ~/deegree.crt --resolve <DEEGREE_HOST>:443:127.0.0.1 -o /dev/null -w "%{http_code} $p\n" \
    "https://<DEEGREE_HOST>$p"
done

200 /
404 /deegree-webservices/
404 /deegree-webservices/config/listworkspaces
404 /deegree-webservices/resources/

(The first line is the landing page; the console, the REST API and /resources live on the loopback address only.)

Step 6: Open the services console

The console and the REST API listen only on 127.0.0.1:8080. From your own computer, open an SSH tunnel:

ssh -i <your-key.pem> -L 8080:127.0.0.1:8080 ubuntu@<public-ip>

then browse to http://localhost:8080/deegree-webservices/ and sign in with DEEGREE_CONSOLE_PASSWORD:

A wrong password is refused. After you sign in, the console shows the active utah workspace, its services, data stores, layers and styles:

Step 7: The REST API

The REST API (/deegree-webservices/config/...) manages workspaces: list, download, upload, restart. Every call needs the header X-API-Key: <DEEGREE_REST_API_KEY>; a call without it, or with another key, is refused. Through the same tunnel:

KEY="$(sudo sed -n 's/^DEEGREE_REST_API_KEY=//p' /root/deegree-credentials.txt)"   # on the instance
curl -s -H "X-API-Key: $KEY" http://localhost:8080/deegree-webservices/config/listworkspaces

Step 8: Check the whole instance

The self-test proves the OGC services over HTTPS (capabilities, a GetMap, a GetFeature and a GetTile), that the console and the REST API are not public, that the REST API refuses a missing or wrong key and an unauthenticated upload, and that the console refuses a wrong password and accepts this instance's:

sudo deegree-selftest

deegree-selftest: WMS GetMap stateboundary PNG, WFS GetFeature app:Airports, WMTS GetTile utah_ortho over HTTPS; console, REST, /resources and path tricks refused publicly; REST refused without/with a wrong key and unauthenticated uploads refused (GHSA-3rr8), accepted with this instance's key; console: wrong passwords refused, this instance's password signed in
DEEGREE_SELFTEST_OK

Step 9: Reach a database or service in your VPC

The egress backstop refuses deegree every private address and this instance's own VPC ranges, so a fresh instance cannot be turned into a scanner of your network through a remote style or XLink. The ranges it read at boot:

sudo deegree-vpc-cidrs --print

source imds
4 172.31.0.0/16

To let deegree use a database or another OGC service on a private address (for example an Amazon RDS for PostgreSQL with PostGIS in your VPC), add its CIDR, one per line, to /etc/cloudimg/deegree-egress-allow, then reload the backstop and restart deegree:

echo '10.0.1.0/24' | sudo tee -a /etc/cloudimg/deegree-egress-allow
sudo systemctl reload cloudimg-deegree-egress && sudo systemctl restart deegree

Only private ranges are accepted (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 and fc00::/7); the metadata service and link-local addresses can never be allowed, and a file with any other entry is refused whole, keeping the previous rules.

If deegree does not start after a reboot. The backstop is fail closed: the instance reads its VPC ranges from EC2 metadata at every boot (with retries), then from cloud-init's copy, then, on later boots only, from the last list this instance recorded. If none of them gives the ranges (for example after the metadata service was switched off on the instance), deegree refuses to start and journalctl -u deegree -u cloudimg-deegree-vpc-cidrs says so. Turn IMDSv2 back on (aws ec2 modify-instance-metadata-options --instance-id <id> --http-endpoint enabled --http-tokens required), then:

sudo systemctl restart cloudimg-deegree-vpc-cidrs cloudimg-deegree-egress deegree nginx

Step 10: Load your own data

A workspace is a directory under /var/lib/deegree/workspaces (the active one is named in webapps.properties). The simplest start is a copy of utah: replace its shapefiles under data/, edit the data store, layer and theme files, and switch to it in the console (workspaces, then Start) or with the REST API. The deegree documentation describes every file: deegree webservices handbook. Workspaces are owned by the tomcat account; edit them with sudo -u tomcat or through the console.

Step 11: Change the console password and the API key

sudo deegree-set-password            # generates a new random password into /root/deegree-credentials.txt
sudo deegree-set-password --stdin    # or reads your own from standard input
sudo deegree-rotate-api-key          # a new REST API key; the old one stops working

Each restarts deegree; changing the password ends every signed-in console session.

Step 12: Use your own domain and certificate

Point a DNS name at the instance, then make it the instance's name. The command writes the nginx host names (requests for any other name are dropped), generates a new self-signed certificate for the names and restarts nginx; the capabilities documents then advertise the new name:

sudo deegree-set-domain deegree.example.com

To use a certificate from a certificate authority instead, put the full chain and key in /etc/ssl/deegree/deegree.crt and /etc/ssl/deegree/deegree.key (root only, mode 0600 for the key), then sudo nginx -t && sudo systemctl reload nginx. If the instance's public address changes after a stop and start, run deegree-set-domain again with the new address.

Step 13: Versions, licences and source

cat /usr/share/doc/deegree/README.cloudimg

deegree on this image (cloudimg)
================================
  deegree webservices 3.6.14   LGPL-2.1-or-later   https://github.com/deegree/deegree3 (tag deegree-3.6.14)
  deegree-webservices-3.6.14.war   sha256 c649043e947cf56eb64051c561a9042107784d9ba67210c68d329e8f8fa48991   sha1 66f5227da0797c9838c23dc61548f9f32508c85c   (https://repo.deegree.org/repository/public/org/deegree/deegree-webservices/3.6.14/deegree-webservices-3.6.14.war)
  deegree-workspace-utah-3.6.14.zip   sha256 ec662561e92e29620511f90a5a07030d1e7bf275bff3003f83cef7595f34f8f4   sha1 1cd18e760b8008be0a88076219d59d574759ecf6   (https://repo.deegree.org/repository/public/org/deegree/deegree-workspace-utah/3.6.14/deegree-workspace-utah-3.6.14.zip)
  Apache Tomcat 10.1.61   Apache-2.0   apache-tomcat-10.1.61.tar.gz sha512 35120a2b1182bac3d55438fbec0dc581d03b0f1c16ce692a930f3bb6a1097cf896b94b389152257071a87cb2928ac8c15f1bad08387c14acc7c17dbc1bb598fb
OpenJDK 17, nginx and every other package are from the Ubuntu 24.04 main archive. deegree is shipped UNMODIFIED
(the WAR is exploded byte for byte: webapp-jars.sha256); its corresponding source is the tag above
(https://github.com/deegree/deegree3/archive/refs/tags/deegree-3.6.14.tar.gz). The demo workspace
"utah" is deegree's own (data from the state of Utah, via deegree); the remote WMS cascade layer was removed and
service limits (WMS 4096 x 4096 / 16 layers, WFS 10000 features) were added. cloudimg packages and configures
deegree; deegree is not endorsed by or affiliated with cloudimg.

deegree is free software under the GNU Lesser General Public License version 2.1 or later; Apache Tomcat is under the Apache License 2.0. The image ships both unmodified; the licence texts and the hash of every file in the deegree web application are in /usr/share/doc/deegree. The Utah demo data comes from the State of Utah through the deegree project.

Ubuntu's unattended upgrades keep the operating system, OpenJDK and nginx patched. deegree and Tomcat do not update automatically: the cloudimg listing adds a new version when they release one. To keep your work across a move to a new instance, copy your workspace directories from /var/lib/deegree/workspaces.

deegree is developed by the deegree project (OSGeo) and lat/lon GmbH. cloudimg packages and configures it and is not affiliated with or endorsed by the deegree project.

Support

cloudimg provides support for this image by email at support@cloudimg.co.uk, 24 hours a day, 7 days a week. Tell us the AMI ID and Region, and include the output of sudo deegree-selftest and systemctl status deegree nginx cloudimg-deegree-vpc-cidrs. For questions about configuring workspaces, see the deegree documentation and the deegree mailing lists.