geoCML v0.3.1 Documentation

geoCML deployments include four containerized microservices: geocml-desktop (the primary user entrypoint), geocml-server (the secondary user entrypoint), geocml-postgres (the primary data store), and geocml-task-scheduler (an automation service, often abbreviated as gTS). Each service can communicate via an internal network called geocml-network. Once deployed as a geoCML instance, you can begin using geoCML to complete GIS workflows. By design, each geoCML instance should host only one project/dataset. Multiple datasets should be hosted across multiple geoCML instances. Specific documentation on each service is available for your reference.

geoCML deployments come out of the box with a variety of features:

geoCML is currently limited in the following areas:

geoCML base deployments are customizable to fit your specific needs. You can customize your services however you’d like! If you would like to contribute to the development of geoCML, you can find the project on GitHub at github.com/geocml.

Get up and running with geoCML in under 15 minutes!

geoCML deployments are multi-paradigm, offering a desktop, server, and web GIS experience with a single deployment. You may host your geoCML instance locally or in the cloud, depending on your needs.

Before instantiating a geoCML deployment, you must have Docker and Docker Compose installed on the machine you want to host geoCML on. You do not need any additional GIS software installed on the host machine. Once you have satisfied these conditions, please follow the following steps to deploy your geoCML instance.

That’s it! You can access geoCML Desktop via {deployment host URL}:10000 or geoCML Server Portal via {deployment host URL}:80 using a web browser. Further configuration steps for each of these services are discussed in later topics.

The geoCML development team hosts pre-built containers at our container registry on Github. These containers are a great way to demo geoCML, but please note that these services are not production ready, because they lack the required build arguments. If you want to use geoCML in production, please build your containers.

Please keep in mind that the GEOCML_DESKTOP_PASSWORD variable in the .env file must be set to access your deployment via geoCML Desktop.

After instantiating your geoCML deployment, you can connect to geoCML Desktop via a web browser at {deployment host URL}:10000.

geoCML Desktop is designed to be a replacement for your typical desktop GIS experience. With the default geoCML Desktop, you can:

You may want to extend the default geocml-desktop service with additional applications or configurations that meet your needs. geoCML Destkop has a two step configuration process: Dockerfile configuration, and Ansible configuration.

geoCML deployments do not persist data; the file system within the service should not ever be changed directly unless during the build process. You may wonder how, then, are you to upload and change datasets contained within the geoCML Desktop service?

The persistence layer is a mutible and persistent directory shared between the geoCML Desktop service and the deployment’s host machine. geoCML Base Deployments use Docker to bind the host machine’s local persistence layer to a persistence layer within the geoCML Desktop service. This binding allows you to add files to the host machine’s persistence layer and have them available within the geoCML Desktop service. The persistence layer is also be available to other services within the deployment.

geoCML Postgres can be fully configured to suit the needs of your use case. geoCML Postgres has a two step configuration process: Dockerfile configuration, and Ansible configuration.

geoCML Postgres creates a database named geocml_db, which is the primary datastore for your geoCML project. Do not change the name of this database! You can access your database in several ways:

The default credentials for accessing your database are:

geoCML Postgres also configures an admin user for your data store. The default credentials for accessing your data store as an admin are:

You can change the default password for both the geocml and postgres users in your deployment’s .env file. Note that these are build-time arguments; you must rebuild your containers to commit these changes.

In geoCML v0.3.0, there are known limitations with the geoCML Postgres service. Currently, geoCML Postgres does not support the following data:

If you are working with raster data, please store them in the persistence layer rather than in geoCML Postgres.

geoCML Server can be fully configured to suit the needs of your use case. geoCML Server has a two step configuration process: Dockerfile configuration, and Ansible configuration.

geoCML Server Portal is accessible via {deployment host URL}:80. geoCML Server Portal is a web application frontend for geoCML Server written in React. geoCML Server Portal acts as the secondary user entrypoint for your deployment, allowing you to share data with others over the internet. geoCML Server Portal relies on Web Map Service (WMS) information from geocml-project.qgz in order to properly display your instance information.

geoCML Server Portal features:

geoCML Server exposes all API functionality for QGIS Server via cfcgi and Apache. Learn more about QGIS Server here: https://docs.qgis.org/3.34/en/docs/server_manual/index.html

geoCML Task Scheduler can be fully configured to suit the needs of your use case. geoCML Task Scheduler has a two step configuration process: Dockerfile configuration, and Ansible configuration.

geoCML Postgres is not a persistent data store. Because of this, when your geoCML instance goes down, you will risk losing information in your data store. geoCML Task Scheduler handles this by automatically backing up geocml_db every hour. When your instance is brought back up, geoCML Task Scheduler will automatically restore your data store from the most recent backup. Backups are stored in the DBBackups directory in the persistence layer. Each DBBackup contains a .tabor file defining the schema of geocml_db and a series of CSV files representing the actual data in your tables.

You can create custom tasks in geoCML Task Scheduler.

Your new task is created, and it is scheduled for execution.

Tabor can be downloaded directly from https://github.com/geoCML/tabor. After downloading, simply extract the downloaded .zip file to a directory accessible on your terminal path.

tabor read --file <path/to/file> → Converts a .tabor file into a PostGIS schema query.

tabor write --file <path/to/file> --db <name_of_psql_db> --username <name of db user> --password <password of db user?> --host <host of psql db?> --port <port of psql db?> --ignore <tables to ignore?> → Converts a PostGIS database to a .tabor file

tabor load --file <path/to/file> --db <name_of_psql_db> --username <name of db user> --password <password of db user?> --host <host of psql db?> --port <port of psql db?> → Loads a PostGIS database from a .tabor file.

Tabor supports the following geometry types:

If a layer has no geometry type, it may still be defined as a non-geometric table in the database.

The spatial reference of each layer in your Tabor file can be defined with the srid field, followed by the SRID of your reference system.

Tabor supports the following primitive field types:

Tabor also supports arrays of primitive data. You can define an array as type: <primitive> array

It is strongly recommended that you have a primary key (pk) on each of your layers. You can define a field as a primary key using pk: true.

You can define complex business logic in your Tabor file with data constraints. Data constraints ensure that changes to your database table meets specific rules before they are committed to the database. You can choose to include as many data constraints on your layers as you need.

Tabor supports the following data constraints:

ex.

ex.

ex.

Before interacting with DRGON, you must first have a hosted geoCML deployment with a properly configured geoCML Server Portal. Next, register for an API key via a POST request to <DRGON_HOST>/apikey; You must provide an email address in the request body. Copy your API key to a safe place, you will only be able to view it once!

On your deployment’s server machine, add the following values to your .env file:

Rebuild your geoCML deployment, and restart your instance. After about a minute of up-time, geoCML Task Scheduler will ping DRGON and automatically register your deployment.

You can host your own dedicated DRGON instance with a few simple steps:

Whoever hosts a DRGON instance is free to moderate their registry however they wish. DRGON automatically moderates deployments containing banned words (e.g. offensive words), however manual review and moderation of deployments in your registry is highly recommended.

The DRGON development team recommends that you prevent users from abusing your registry, either by uploading duplicate datasets, or by registering non-geoCML deployments. If a user is abusing your registry, you can revoke their API key within the drgon-postgres service database.