Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nikaplanet.com/llms.txt

Use this file to discover all available pages before exploring further.

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: 
name: my-worker
version: "1.2.0"
local_tag: "1.2.0"
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.
Dev (--dev)Production (no flag)
Version checkSkippedEnforced
Image tagged aslatest only<worker-id>:<local_tag> + latest
Config snapshot savedMutable latest snapshotTagged snapshot + latest
Reproducible laterNoYes — via --tag
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. 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 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 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 run --actor CLI --tag 1.0.0 --input input-file=/path/to/data.tif
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): 
geoengine delete --tag 1.0.0
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>: 
geoengine delete

​
Example Versioning Workflow

# --- Development phase ---
# Iterate freely without bumping the version
geoengine apply --dev    # updates mutable latest
geoengine apply --dev    # overwrites latest again

# --- Ready for release ---
# Bump version in geoengine.yaml to 1.0.0, then:
geoengine apply          # saves snapshot, creates local tag 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, creates local tag 1.1.0 + latest

# --- Run a specific old build by its local tag ---
geoengine run --actor CLI --tag 1.0.0 --input input-file=/data.tif