This repo both hosts a deployed instance of TGVE on GitHub Pages, and acts as a template that you can use to deploy your own instance.

Deployed latest version

The latest release is deployed at https://tgve.github.io/app. You can pass your own geospatial data URL as defaultURL=url parameter as follows:

https://tgve.github.io/app?defaultURL=https://raw.githubusercontent.com/tgve/example-data/main/casualties_100.geojson

You should see something like:

Likewise, you can embed it in an iframe as follows (this document is restricted to certain HTML elements, excluding iframe):

<iframe srce="https://tgve.github.io/app" />

See the example notebook for how to embed the application into a Jupyter notebook.

Hosting your own instance

With this template repository, it is easy to host your own instance of the Turing Geo-visualization Engine (TGVE), via GitHub Pages. To achieve this, follow these three steps:

1. Create repo from this template

You should now have a copy (not fork) of the repo at https://github.com/USER_OR_ORG/YOUR_REPO_NAME. The actions may not start running at this stage. In the next step we will make sure this happens.

2. Edit REACT_APP_DEFAULT_URL in build-deploy.yml with the URL of your dataset. To pass separate data and geography URLs, use REACT_APP_GEOGRAPHY_URL, REACT_APP_GEOGRAPHY_COLUMN and REACT_APP_COLUMN, as described here. Check out src/App.js to see how you can pass these variables to the TGVE React component.

3. The GitHub Actions defined in .github/workflows are responsible for building and deploying the app. Once the first build is complete, it will create a separate branch called gh-pages. Enable deployment to GitHub Pages by set gh-pages as the branch and root as the directory in your repo's GitHub Pages settings:

You should now have an instance at https://USER_OR_ORG.github.io/YOUR_REPO_NAME. Note that publishing to GitHub Pages may take some time.

What did we do? The repo now has a branch called gh-pages which GitHub uses to serve the app; the app will pull data from the link added in step (2). The following screenshot shows a repo with owner “layik” and repository name “eAtlas”:

The example data file includes point data with geography defined in the columns. TGVE is able to extract the points from the CSV file using the csv2geojson package from Mapbox. You can set your own Mapbox API key by providing MAPBOX_KEY as a GitHub secret; see REACT_APP_MAPBOX_ACCESS_TOKEN in build-deploy.yml.

Local hosting

To run locally, ensure yarn is installed. Then:

1. Clone this repository
2. Run yarn
3. Run yarn start

Then visit http://localhost:3000 to see the running application.

Serving the app from R or Python

See the following READMEs for documentation.

• Python (using Flask)
• R (using Plumber)

Technical notes

• react-scripts locked to 3.4.4 due to a url-loader issue.