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.

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 Script

Download the starter worker script and save it in an isolated folder somewhere on your machine — your home directory or Desktop works fine.
For this example, we will assume you created a directory in /Users/<user>/Downloads/grid-creator. Place the script into this directory.
You should now have a folder called grid-creator in your current directory.

​
Step 2 — Navigate Into the Directory

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

​
Step 3 - Initialise the Worker

First, you have to generate the worker artifact templates. Run the following in the same terminal. 
geoengine init --env py
Here, we specify the --env flag to create a Python-centric dependencies template. If you were to use an R script, use --env r instead.

​
Step 4 — Inspect the Files

Take a moment to look at what’s inside before running anything:

​
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
  • geoengine.lock - the ID of the worker (do not touch this)

​
Step 5 - Wire up the Script

Ensure that your script has an argparser set up. If you look at the script, you will notice it is already done. So now, we just need to wire up the config files to match the script.

​
Add Dependencies

Open up pixi.toml in an editor of your choice. Here, you can edit the [workspace] section if you wish. This will not be reflected anywhere, but is just a mere requirement of Pixi. You will also notice that the base dependencies have already been set up for you after geoengine init in the [dependencies] section. These are sufficient for this script, but if you require additional dependencies, add them below the base ones.

​
Edit the Config File

Open up geoengine.yaml in an editor of your choice. Here, you will define the worker’s details. From its name, description, to its input parameters and mounts.
  • The template creates the worker name based on your directory folder, but feel free to change it as you wish.
  • The version section is important later, but for now you can leave it at 1.0.0.
  • The description field will be write-up on your worker’s workings. Optional, but good to have.
  • The command section details out the running requirements of your worker. The inputs should match the arguments set up in the argparser in your script.
  • plugins switches enable/disable the worker in the corresponding GIS platform. We will look at it later.
For this example, copy and paste the below configuration wholesale into the geoengine.yaml. 
name: grid-creator
version: 1.0.0
description: Create square, rectangle, or diamond grids from an input vector extent
command:
  program: python
  script: grid_creation.py
  inputs:
  - name: input-file
    type: file
    required: true
    description: Input vector file used to derive the grid extent
  - name: grid-type
    type: enum
    required: false
    default: square
    description: Grid geometry type
    enum_values:
    - square
    - rectangle
    - diamond
  - name: cell-width
    type: number
    required: true
    description: Grid cell width in CRS units (or meters when auto-reproject is true)
  - name: cell-height
    type: number
    required: false
    description: Grid cell height for rectangle grids (optional for square/diamond)
  - name: output-file
    type: string
    required: false
    default: regular_grid
    description: Output file name without extension (GeoJSON will be written)
  - name: output-dir
    type: folder
    required: true
    description: Output folder for the generated GeoJSON grid
    output: true
  - name: auto-reproject
    type: boolean
    required: false
    default: true
    description: Auto-reproject geographic CRS inputs to UTM while generating the grid
  - name: add-id
    type: boolean
    required: false
    default: true
    description: Add a grid_id column to the output
plugins:
  arcgis: false
  qgis: false

​
Step 6 — 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/<uuid>: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 7 — 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.
Wait a second… Where IS the plugin?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
Since this is the first worker, you will be prompted to install the plugin. Allow it, restart QGIS, then, go back to the above steps to enable the plugin.This time the output will include:
...
✓ Version latest enabled in QGIS plugin.
✓ Version latest disabled in ArcGIS plugin.
...

​
Processing Toolbox

The GeoEngine plugin should now be available in the Processing Toolbox. Open it from the top bar Processing > Toolbox.
Alternatively, you can use the short cut ⌥+⌘+T.

​
Step 8 — 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 9 — 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 teams, you will be prompted to select the team you wish to push to.
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: