Write your deployment scenario#

What is a scenario?#

This is the main way to use QDT. You write your deployment scenario by describing the steps to be done to prepare the QGIS environment, take a coffee (cup of tea is also tolerated) and look at the scenario running.

In concrete terms, a scenario is a YAML file whose extension (.yaml or .yml) can be suffixed with .qdt so as to be more easily distinguished by the tool in the midst of potential other YAML files. Example: scenario.qdt.yml. The syntax is largely inspired by DevOPS oriented tools like Ansible or CI/CD platforms (GitHub Actions, GitLab CI in particular).

A scenario has 3 sections:

  • metadata: to describe the scenario (title, description, etc.)

  • settings: to set execution parameters to be applied to QDT, in the form of keys/values

  • steps: the steps that the deployment scenario will successively take. Each step can call for a “job”.

By default, QDT looks for a file named scenario.qdt.yml in the current directory.
If it is not found, it will expect subcommands to run.

Jobs#

A job is a logical module that is called by a step in a scenario, by passing it parameters. Concretely, each job is a Python module of QDT (here in the code).

A step consists of 3 elements:

  • name: the name of the step

  • uses : the job identifier to use

  • with` : the parameters to pass to the Job

See available jobs

Sample scenario#

For development and test purposes, project provides a sample scenario:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json

# This is a sample of a YAML file for the QGIS Deployment Toolbelt scenario.
# For now, it's more a roadmap than a real description of what it's implemented.

metadata:
  title: "Test scenario of QGIS Deployment Toolbelt"
  id: test-basic-scenario-good
  description: >-
    This is an example a scenario YAML file for the QGIS Deployment Toolbelt to
    demonstrate capabilities.

settings:
  DEBUG: false
  LOCAL_WORK_DIR: ~/.cache/qgis-deployment-toolbelt/tests/
  SCENARIO_VALIDATION: true

steps:
  - name: Set environment variables
    uses: manage-env-vars
    with:
      - name: TEST_PYQGIS_STARTUP
        action: "add"
        value: "~/scripts/qgis_startup.py"
        scope: user
      - name: TEST_FAKE_BOOL
        action: "add"
        scope: user
        value: false
        value_type: bool

  - name: Download profiles from remote git repository
    uses: qprofiles-downloader
    with:
      source: https://github.com/Guts/qgis-deployment-cli.git
      protocol: git_remote
      branch: main

  - name: Synchronize downloaded profiles with installed ones
    uses: qprofiles-synchronizer
    with:
      sync_mode: only_new_version

  - name: Download plugins
    uses: qplugins-downloader
    with:
      force: false
      threads: 5

  - name: Synchronize plugins
    uses: qplugins-synchronizer
    with:
      action: create_or_restore
      profile_ref: downloaded

  - name: Create shortcuts for profiles
    uses: shortcuts-manager
    with:
      action: create_or_restore
      include:
        - profile: qdt_demo
          label: "TEST QDT - Demo profile"
          desktop: true
          start_menu: true
        - profile: QDT Viewer Mode
          label: "TEST QDT - Viewer profile"
          desktop: true
          start_menu: true

  - name: Set splash screen
    uses: splash-screen-manager
    with:
      action: create_or_restore
      strict: false

Validate scenario using JSON Schema#

In order to minimize friction and maximize productivity, the project tries to provide a schema.json for scenarios files. If your editor supports YAML schema validation, it’s definitely recommended to set it up.

Generic#

  1. Ensure your editor of choice has support for YAML schema validation.

  2. Add the following lines at the top of your scenario file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json

Visual Studio Code#

  1. Install the vscode-yaml extension for YAML language support.

  2. Add the schema under the yaml.schemas key in your user or workspace settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/scenario/schema.json": "*.qdt.yml"
  }
}