Skip to main content
This guide walks you through deploying your first GeoEngine worker from start to finish. Every command is ready to copy and paste — just follow the steps in order. A couple of surprises are built in along the way, so don’t skip ahead.
This guide assumes you have already installed GeoEngine and logged in. If you haven’t, complete the Installation & Setup guide first.

​
Introduction

We will be deploying a simple geoprocessing worker that creates a grid around a vector input. The script is written in Python.

​
Step 1 — Download the Starter Worker

Download the starter worker folder here and save it somewhere on your machine — your home directory or Desktop works fine.
Double-click the .zip file to unzip .
You should now have a folder called grid-creator in your current directory.

​
Step 2 — Navigate Into the Directory

cd /path/to/grid-creator
All GeoEngine commands from here on must be run from inside this folder.

​
Step 3 — Inspect the Files

Take a moment to look at what’s inside before running anything: 
grid-creator/
├── .dockerignore
├── Dockerfile
├── geoengine.yaml
├── pixi.toml
└── grid_creation.py

​
Main Script

  • grid_creation.py — the Python script that does the actual geoprocessing work

​
GeoEngine Worker Configurations

The following files can be edited to customize the worker:
  • pixi.toml — declares all the Python/conda dependencies GeoEngine will install into the Docker container
  • geoengine.yaml — the worker configuration: its name, inputs, data mounts, and plugin settings

​
GeoEngine Worker Build Artifacts

The following files are automatically generated by GeoEngine, and should not be edited unless you know what you’re doing:
  • Dockerfile — frameworked definition of the build process for your worker
  • .dockerignore — tells Docker which files to ignore when building the image

​
Step 4 — Apply the Worker Locally

Run the following command to build and apply the worker in development mode: 
geoengine apply --dev
GeoEngine will resolve dependencies, build the Docker image, and register the worker on your machine. The first apply takes the longest — pixi is downloading and locking all the packages declared in pixi.toml.
The first geoengine apply --dev can take several minutes while pixi installs dependencies into the Docker image. Subsequent applies are much faster because the image layers are cached. This is completely normal — let it run.
When it finishes, you should see output like this: 
=> Building worker 'grid-creator'...
✓ Successfully built image: geoengine-local/grid-creator:latest
✓ Registered worker 'grid-creator'
✓ Version latest disabled in QGIS plugin.
✓ Version latest disabled in ArcGIS plugin.
✓ Apply complete for worker 'grid-creator'
The worker is now built and registered! You can check details of the worker by running while still in the grid-creator directory: 
geoengine describe

​
Step 5 — GIS Testing

​
Enable the Plugin in QGIS

GeoEngine installs the plugin automatically on apply, but you need to enable it inside QGIS once:
  1. In the QGIS top bar, click Plugins > Manage and Install Plugins…
  2. Go to the Installed tab
  3. Find GeoEngine in the list and check the box next to it
  4. Close the dialog
You only need to enable the plugin once. Future applies and updates will not require you to do this again.

​
Processing Toolbox

The GeoEngine plugin should now be available in the Processing Toolbox. Go on there to check it out.Wait a second… You just applied the worker successfully — the terminal said so. But where IS it?Go back and look at the geoengine.yaml you read in Step 3:
plugins:
  arcgis: false
  qgis: false   # ← here's your answer
The qgis: false flag tells GeoEngine not to register this worker with the QGIS plugin. The apply output even confirmed it: ✓ Version latest disabled in QGIS plugin.. GeoEngine did exactly what it was told — the worker just isn’t wired into QGIS yet.

​
The Fix

Open geoengine.yaml in any text editor and change qgis: false to qgis: true:
plugins:
  arcgis: false
  qgis: true    # ← changed
Save the file, then re-apply in the same terminal that is in the grid-creator directory:
geoengine apply --dev
This time the output will include:
...
✓ Version latest enabled in QGIS plugin.
✓ Version latest disabled in ArcGIS plugin.
...

​
Step 6 — Run the Worker from GIS

In the Processing Toolbox, expand GeoEngine and find my-worker. Double-click it to open the tool dialog.Load a vector layer as the Input Layer — any polygon or line layer you have on hand works for a first test run. You can even load in a vector file. Click Run.GeoEngine executes the script inside the Docker container and streams the output back to QGIS. When it finishes, a result layer will appear in your Layers panel and render on the map canvas.
If the tool dialog does not appear or the worker shows an error, check the GeoEngine Log panel (View > Panels > GeoEngine Log) for the full output from inside the container.

​
Step 7 — Push to the Cloud

Once you’re happy with how the worker runs locally, publish it so your whole team can access it. Pushing requires a production apply, so first make sure geoengine.yaml has a valid version (e.g. 1.0.0) and run: 
geoengine apply
Then push the image to the cloud: 
geoengine push
GeoEngine tags the image with the version from your geoengine.yaml and uploads it to the Nika registry. If you have access to multiple tenants, use --tenant <tenant> to target a specific one.
After pushing, the worker is available to everyone in your Nika organisation — in QGIS, ArcGIS Pro, and the Nika web platform — without them needing to run geoengine apply themselves.

​
Next Steps

You’ve gone from a zip file to a live cloud-deployed geoprocessing worker. Here’s where to go from here: