Skip to main content
GeoEngine uses Semantic Versioning to track worker builds. Every production apply creates a permanent snapshot of the worker configuration, so any version can be reproduced and run at any time — even after the code has changed.

​
Version Format

Worker versions follow the MAJOR.MINOR.PATCH format, set in geoengine.yaml: 
name: my-worker
version: "1.2.0"
All three 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 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.
Dev (--dev)Production (no flag)
Version checkSkippedEnforced
Image tagged aslatest only<version> + latest
Config snapshot savedNoYes
Reproducible laterNoYes — via --ver
Appears in GIS by versionNo — latest onlyYes

​
During Development

Use --dev to iterate freely without worrying about version numbers: 
geoengine apply --dev
The image is tagged as latest and no snapshot is saved. Running geoengine apply --dev again will overwrite latest, 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 apply
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
If any of these checks fail, the apply is rejected with an error.

​
Running a Specific Version

To run a previously-built version instead of latest: 
geoengine run my-worker --ver 1.0.0 --input input-file=/path/to/data.tif
GeoEngine loads the snapshotted configuration for that version and runs the corresponding Docker image. This works regardless of what the current geoengine.yaml says — the snapshot is self-contained. If --ver 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 my-worker (without --ver) 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 run via version number.

​
Deleting a Version

To remove a specific version (its Docker image, mapping entry, and snapshot): 
geoengine delete --ver 1.0.0
The version check during the next geoengine apply always reads the live map.json, so deleting an older version does not affect the minimum allowed version for the next apply. To remove a worker entirely: 
geoengine delete --name my-worker

​
Example Versioning Workflow

# --- Development phase ---
# Iterate freely without bumping the version
geoengine apply --dev    # tags as latest, no snapshot
geoengine apply --dev    # overwrites latest, still no snapshot

# --- Ready for release ---
# Bump version in geoengine.yaml to 1.0.0, then:
geoengine apply          # saves snapshot, tags as 1.0.0 + latest

# --- Iteration after release ---
geoengine apply --dev    # dev build overwrites latest
geoengine apply --dev    # keep iterating

# --- Next release ---
# Bump version to 1.1.0, then:
geoengine apply          # saves snapshot for 1.1.0, latest = 1.1.0

# --- Run a specific old version ---
geoengine run my-worker --ver 1.0.0 --input input-file=/data.tif