Cloud Native Geospatial (CNG) Tutorials

Overview

This repository contains code for creating a website of tutorials about Cloud-Native Geospatial (CNG) technologies.

Interacting with the tutorials

Viewing

The tutorials are hosted as static webpages on the website: vorgeo.github.io/cng-onboarding/ To browse through the available tutorials, use the navigation menu on the left side.

Executing the Code

Local Execution (with Pixi)

Requirements:

  • Local install of git
  • Local install of pixi

Steps:

  1. Clone the repo: git clone https://github.com/VorGeo/cng-onboarding.git
  2. Navigate to a tutorial directory. For example: cd tutorials/stac/python/python-read-stac/
  3. Run the start task to start up JupyterLab: pixi run start
    • This will install the tutorial’s code dependencies, start a JupyterLab server, and open up the tutorial in a browser window.

Local Execution (with Dev Containers)

Requirements:

Steps:

  1. Clone the repo: git clone https://github.com/VorGeo/cng-onboarding.git
  2. Open the cloned repo in VS Code.
  3. Open the command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and select “Dev Containers: Rebuild and Reopen in Container”.
    • Select the Container for the tutorial you want to run.
  4. Once the Container is built, you can open up the notebook (index.ipynb) from the Explorer menu.

Cloud Execution (with GitHub Codespaces)

Requirements:

  • A GitHub account

Steps:

  1. Within the website (https://vorgeo.github.io/cng-onboarding/), open one of the tutorial pages.
  2. Click on the ‘Open in GitHub Codespaces’ button.
  3. In the “Create codespace” page, modify the selection options as needed and then click “Create codespace”.
  4. A new Codespace will be started. It can take up to 5 minutes for the codespace to be configured, at which point you will see the message “Finished configuring codespace.” in the terminal tab.
  5. Once the codespace is ready, you can interact with the tutorial in the same way as you would in a local environment. Open up the notebook (index.ipynb) and start executing the cells.
    • You may need to specify the kernel to use for the notebook. To do this, click on the kernel name in the top right corner of the notebook and select the default kernel (e.g., .pixi/envs/default/bin/python).

Contributing

Contributing to an existing tutorial

[TODO… Describe how to contribute changes to a tutorial.]

Creating a new tutorial

  1. Create a new tutorial repo by cloning the template repo
  2. Draft the tutorial
    • Update the pixi environment by either running pixi add <PACKAGE> or by editing the pyproject.toml file.
    • Edit the index.ipynb file to add tutorial content.
    • Preview the tutorial by running quarto preview in the tutorial directory.
  3. Add the tutorial to the main website
    • Add the tutorial repository to this repository as a submodule
      • git submodule add <TUTORIAL_REPO_URL> tutorials/<TUTORIAL_NAME>
      • git submodule update --init --recursive
    • Add the tutorial to navigation by editing the _quarto.yml file

Colophon

The website makes use of several technologies, including:

Technology Description
Quarto Quarto is used to generate a static HTML website. Quarto configuration is contained within the /_quarto.yml file, and in a raw cell at the start of each tutorial notebook.
Pixi Pixi is used for package management, and is part of the conda ecosystem. Each tutorial defines its own code environment configuration in a pyproject.toml (for Python tutorials) or pixi.toml (for non-Python tutorials) file. Pixi solves for an environment that honors the configuration and stores the result in a pixi.lock file.
GitHub Actions GitHub Actions are used for continuous integration and deployment. Changes that are commited to main branch trigger rebuilding of the static website. Configuration of the actions can be found in the .github/workflows/ folder.
GitHub Pages GitHub Pages is used to host the website.
Development Containers Dev Containers define a full-feature development environment that can be run either locally or in the cloud. Configuration of the dev container can be found in the .devcontainer/ folder.
GitHub Codespaces (Optional) GitHub Codespaces can be used for cloud-based development.