Skip to main content
GeoEngine uses Semantic Versioning for cloud-facing worker releases and a separate local_tag for local builds. Every production apply records a local tag and a config snapshot, so any past production build can be reproduced and run later — even after the code has changed.

​
Versions vs Local Tags

These two concepts are related but distinct:
  • Version — the semantic version string you set in geoengine.yaml (e.g. 1.2.0). It follows MAJOR.MINOR.PATCH rules and is enforced by GeoEngine during production applies. This is the version sent to the cloud when you push.
  • Local tag — the local build label GeoEngine uses for Docker tags and saved snapshots. Set it with local_tag in geoengine.yaml when you want a named local build (for example release-candidate). If you omit it during a production apply, GeoEngine asks whether to use the version value as the local tag.
You reference a specific past build using its local tag (for example --tag 1.2.0 or --tag release-candidate), not necessarily the raw semantic version.

​
Version Format

Worker versions follow the MAJOR.MINOR.PATCH format, set in geoengine.yaml:
All three version components are required. Examples of valid versions: 1.0.0, 0.3.1, 2.10.4. A version like 1.0 or 1 is invalid and will cause a production geoengine apply to fail. As a general guide:
  • PATCH (1.0.0 → 1.0.1) — bug fixes, small script tweaks, no change to inputs or outputs
  • MINOR (1.0.0 → 1.1.0) — new optional inputs, improved output, backwards-compatible changes
  • MAJOR (1.0.0 → 2.0.0) — removed or renamed inputs, changed output format, breaking changes

​
Dev vs Production Applies

GeoEngine has two apply modes. Which one you use determines whether versioning is enforced and whether a snapshot is saved.

​
During Development

Use --dev to iterate freely without worrying about version numbers:
The image is tagged as latest. Running geoengine apply --dev again overwrites the mutable latest image and latest config, even if a prior production version exists.

​
For Production Releases

When the worker is ready to share or use in GIS tools, apply without --dev:
GeoEngine will enforce that:
  1. The version field is present in geoengine.yaml
  2. The version is a valid semver string (MAJOR.MINOR.PATCH)
  3. The version is greater than or equal to the highest version currently recorded locally
  4. The selected local_tag is not latest and does not already point to different content
If any of these checks fail, the apply is rejected with an error. If local_tag is missing, GeoEngine prompts you to use the version string as the local tag. Accepting this is fine for normal releases; add an explicit local_tag when you need multiple local builds for the same version.

​
Running a Specific Tag

To run a previously-built local tag instead of latest:
GeoEngine loads the snapshotted configuration for that tag and runs the corresponding Docker image. This works regardless of what the current geoengine.yaml says — the snapshot is self-contained. If --tag is omitted, geoengine run always uses latest, which tracks the most recent apply (dev or production).

​
The latest Tag

latest always points to the most recent apply, regardless of mode:
  • Running geoengine apply --dev after a production apply will overwrite latest with the dev state
  • Running geoengine apply (production) also updates latest to that version
This means geoengine run (without --tag) and GIS plugin latest entries always reflect the last apply. If you need a stable, pinned version in GIS, always use a production apply and reference it by its local tag.

​
Deleting a Tag

To remove a specific local tag (its Docker image, mapping entry, and snapshot):
The version check during the next geoengine apply always reads the live map.json, so deleting an older tag does not affect the minimum allowed version for the next apply. To remove a worker entirely, run from the worker directory or pass --id <worker-id>:

​
Example Versioning Workflow