terrastories / terrastories

Terrastories is a geostorytelling application for mapping, managing and sharing place-based stories.

About Terrastories

Terrastories is an open-source geostorytelling application for mapping, managing and sharing place-based stories. The application is being co-created with Indigenous and other local communities to collectively manage their oral histories and other cultural knowledge, but it can be used by anyone to create a map of their stories.

Terrastories is a Dockerized Rails and React app that uses Mapbox GL JS / MapLibre GL JS to help users locate place-based media content or narrative stories on an interactive map. As a local-first application, Terrastories is designed to work entirely offline, so that remote communities can access the application entirely without needing internet connectivity.

The main Terrastories interface is principally composed of an interactive map and a sidebar with media content. Users can explore the map and click on activated points to see the stories associated with those points. Alternatively, users can interact with the sidebar and click on stories to see where in the landscape these narratives took place.

By means of a content management system, users with the right level of access can also explore, add, edit, remove, and import stories, or set them as restricted so that they are viewable only with a special login. Users can design and customize the content of the interactive map entirely.

There is also Explore Terrastories, a separate React app that allows public exploration of unrestricted stories that communities have opted into sharing. Explore Terrastories queries the API of the main Terrastories application provided in this repository.

Learn more about Terrastories on our website.

❗️ The remainder of the documentation on Github is for developers. For documentation on using Terrastories, or setting up Terrastories on an online, offline "Field Kit", or mesh network server, please visit the Terrastories Support Materials at https://docs.terrastories.app/

Terrastories: Matawai Konde 1.0 (October 2018)

Install Terrastories

Terrastories can be set up for different hosting environments, including online, local (development), mesh network, or offline "field kit". For local or offline hosting, there is a convenience script that walks you through all of the steps, or you can choose to follow the more granular guides for the various environments and operating systems.

Prerequisites

Docker

Local development and offline mode both require Docker to be installed.

Download and install Docker for your platform.

NOTE: Windows requires WSL 2.0 or virtualization in order to work. Additionally, it is possible that you may need to configure some additional settings for Terrastories to properly work on Windows.

Tileserver (Offline "Field Kit" Mode)

If you plan on running Terrastories offline, you'll need to configure local tiles for offline use.

A default, open-license map for using offline with Terrastories is available at https://github.com/terrastories/default-offline/tiles. You will have the option of downloading these using the setup script below. Alternatively, you can manually download these files and place them in the tileserver/data directory, and they should work when you load Terrastories in Field Kit mode.

Setup

1. Clone this repository
2. Run

   $ ./bin/setup

   and follow the prompts.

Once you have set up Terrastories, you can log in to the super admin console, or the sample Terrastories community, using login information found in rails/db/seeds.rb.

If you are developing with an online (Mapbox) map, you will need to provide an access token. Copy the contents of the .env.example file into a newly created file called .env (Do not change .env.example!). In the .env file, replace where it says pk.set-your-key-here (after DEFAULT_MAPBOX_TOKEN=) with your mapbox access token.

Issues?

Review more granular setup options in the Setup documentation.

Developing with Terrastories

To find out how to develop with the Terrastories app, read our developer guide and check out our Developer Community pages on the Terrastories website.

For a Vision statement and Roadmap, please see our Wiki.

Contributing

Please visit our contributing page for more details.

terrastories's Issues

Controller interface for searching and adding tags to Stories and Points

Media file uploads

Responsive design for the app!

Put basic responsive styles into place, including a minimal navigation that will work properly on mobile devices.

Use administrate library for admin interface of models

Let's use this handy gem by thoughtbot:
https://github.com/thoughtbot/administrate

and set up an admin interface to create, edit, & delete our models: Story, Point, Speaker

Be sure to include Devise hooks here to make sure the user is logged in before they can access these pages.

Restrict the zoom-out level of the map

The main view has a javascript snippet to initialize the MapBox map instance. There should be a way to add max and min zoom levels in that config.

As I understand it higher numbers for zoom level mean the map is zoomed in closer and lower numbers mean it's zoomed out. We want to set a minimum zoom that just shows the edges of Suriname without really showing the rest of South America more than necessary. If we can figure out how to prevent panning away from Suriname, that would be great too, but it's probably a separate config option from zoom levels.

Also, our map data doesn't include any details beyond zoom level 13, so we want to prevent users from getting zoomed in any closer than that. Presumably, there's a maximum zoom config for that, as well.

Toggle map orientation between "north" and "up"

The Matawai people typically orient their maps so that the highest point in a region is "up." This makes most conventional maps feel upside down for them, because the terrain elevation in Suriname goes from higher in the South to lower in the North.

Add a UI feature to toggle between the two orientations.

Bonus points for automatically switching based on locale.

Set up Devise

https://github.com/plataformatec/devise

Handle clicking on a point in the map

Allow a user to click a point displayed on the map and load any stories associated with that point. This should include the point title, text description, and the video for the story (as proven out in #25

Add a permission level field to Stories

Some stories can be viewed by any user, anonymous or not. Other stories can only be viewed if the user is logged in. Let's add a field to Stories that allows Editors to set the permission level (public or private).

Set up Rspec

Build Story model

Title
Description
Speaker
Video/Photo/Audio
Tags
One to One Relationship with Point

Convert view partials to use React components

To keep the UI simple, we want most user actions to occur directly on the map page. Searching, filtering, and creating stories and points should be accessible through a JSON API. We'll use React components to encapsulate the view and update them through the props changes as new data becomes available via AJAX.

As a prerequisite for any of this, we need get the React/Rails integration up and running.

Display story information from the database in the card

When a user clicks on a point or clicks on a story in the list, let's display the story information (Title, Speaker, Video) in the floating card.

Improve look, feel and functionality of login experience

Title says it all :)
We currently use devise, but let's make the login experience UI better.

Allow Stories to be filterable thru the UI

Let's use the model attributes as filters in the UI. Currently, in the Card component, we have a space for three drop downs which will act as our filters.
Changing the filter would change which points and stories are visible in the map and in the list.

Categories:
(1) Region
(2) Type of place
(3) Speaker

Ideally, these would be attributes on the Story model that allow them to be sorted by these categories.
Also, allow Editors to update these in the administrate dashboard.

Build Taggings model

Many to Many Relationship (Many Story has many Taggings)
We want Tags and Taggings to be proper models, which ActsAsTaggableOn seems to do well

Internationalization and Localization

The native language of the people of Suriname is Matawai, which none of us speak. Well, Rudo does.

Add support for localization so that we can build the app in English and someone (Rudo) can translate phrases in our app to Matawai.

Add support for switching locales, probably with support for routes beginning with /en/ and /srm/ to distinguish between the two. (It seems "srm" is the official language code for Saramaccan, of which Matawai is a dialect, I guess.)

http://guides.rubyonrails.org/i18n.html

[Map] Add style.json validation to tilebuilder

When generating mbtiles from shapefiles, any discrepancy between the shapefile names in tilebuilder/shapefiles and the source-layer attributes for the layers in style.json will cause a runtime error in the browser when attempting to render the map.

We can guard against this by validating each layer's source-layer while iterating through the shape files in tilebuilder/scripts/convert.sh. Since most styles will be generated by the online tool provided by MapBox, we're normally only concerned with stripping 6-character alphanumeric hash suffixes matching /-\w{6}/.

Add panning & zooming when you click on a point

When you click on a point, right now, it displays the marker and shows its stories in the card.
But it would be great if the map panned & zoomed a bit up to that point when it's "active".
Check out these links for more info:
https://www.mapbox.com/mapbox-gl-js/example/center-on-symbol/
https://www.mapbox.com/mapbox-gl-js/example/flyto/

Update the introduction text "What is a Terrastory?"

Use the following text:

Terrastories are audiovisual recordings of place-based storytelling. This offline-compatible application enables local communities to locate and map their own oral storytelling traditions about places of significant meaning or value to them.

Build Story model

Build Story model
Title
Description
Speaker
Video/Photo/Audio
Tags
One to One Relationship with Point

[Map] Fix sprite rendering in the style json for tileserver

Currently, sprites are not working on the map and the following errors appear on dev tools console:

We also need a workflow for adding custom SVG's for graphic icons. This map (https://amazonteam.org/maps/matawai-oral-histories/map.html) has some icons for point features:

How can we get these to render in Terrastories?

Create pundit policy for editors

Add a policy in Pundit for Editors
Editors can be defined as a user who can see all stories, add new stories, and edit stories
Make sure to include the check for this policy when viewing, adding, and editing stories

Create homepage with login form

Currently the index roots to the view of the map.
Let's update so there is a homepage view where the user can log in.

Play back a video in the browser

This is a simple technical proof-of-concept that we can request a video as a static asset served from nginx under /media and have the browser load it for playback in a <video> tag. Simply hard-coding this in the placeholder "click on a point on the map" modal will suffice.

Make the introduction disappear on scroll, keep the search bar & logo sticky

Update our CSS so that when the user scrolls in the card, the introduction disappears (but reappears when you scroll back up) and the search bar & logo are in a fixed position.

To achieve this you could make only the container under the logo scrollable, and set the position of the search/filter bar to be fixed.

Database persistence in docker

Currently every time the mariadb docker container restarts, it starts completely blank. We need a strategy for persisting the database somewhere. This should be pretty straightforward using a docker volume: https://docs.docker.com/storage/

Keep in mind that backing up and swapping out data sets will be useful too, so keep that in mind while solving for basic persistence.

Show points on the map

Connecting the points from the backend to the frontend map, instead of using hardcoded data

Improve the look and design of map info balloons

These are the little balloons that pop up when you click on a point. They could be updated with better styling and UI.

[UI] Add coach marks for the first load of the map

When a user visits the map the first time, display coach marks with some information to help the user understand how to navigate terrastories.

Bonus points for finding a descriptive icon instead of using "Scroll to Zoom" words.

Set up Pundit

https://github.com/varvet/pundit

Ignore this ticket.

Just seeing what happens if I convert a ticket/note to an issue

Make documentation markdown files

We'll need two:

1. How to add different languages to the I18n
2. How to replace the map

[Server side] Guard against running bundler and rake tasks in local environment

This project is set up to use Docker to help reduce the burden of configuring a new local development environment for every new contributor. It works great when it works, but an obvious flaw is that any developer can still run the app in their local environment, which may introduce the very environment-specific discrepancies that Docker is supposed to ward off, such as bundler version warnings.

I'm sure a talented open-source community member can figure out a way to prevent running rails directly in a local environment, or at least warn the developer about it. Either way, we should provide clear messaging with links to our documentation about the correct way to run rails-y stuff in this project.

Speaker photo does not work

In the Speaker model, there's a field to select a photo from your system to add to the Speaker. However that photo doesn't show up anywhere, and there's a Rails error when you try to view a Speaker.

We should also make sure that the Speaker name and photo is displayed next to each story.

Setup Active Support for uploads

Update the seed data

Let's update the seed data:
More data - speakers, points, stories
Connect them - which points have which stories
Incorporate videos into the stories
Incorporate photos with the speakers

Improve look, feel and functionality of all editing user flows (add, edit, delete)

This is separate from the administrate issue but could be combined. I kept it separate for now so this issue is focused more on the UI and styling, and the administrate issue is focused on adding the gem and functions.

Build Speaker model

name
photo
region
community

Change UI colors and CSS tweaking

Let's match our visual design recommendations a bit better :)

Add our font files

So we can use our pretty font without having to connect to online

Main UI View - Floating card, story list, story point

Will drop in comp pictures when Jazz uploads them.

We'll need to build the UI for:

• Floating card
• List view in the card
• Story view when you click on a story
• Story point speech bubble

Create Admin policy for Pundit that allows admin to sign up and delete users

We've installed Pundit as a gem in our Rails app but we need to add some policies.
Let's start with an admin user role that would allow them to add and delete regular users.
You can use Devise to handle the logging in & sign up interfaces. Include a policy check to make sure the user is an admin that can sign up new regular users.

Here are the docs for Pundit and Devise:
https://github.com/varvet/pundit/blob/master/README.md#policies
https://github.com/plataformatec/devise/wiki

Make the search icon clickable and turn it into a search bar

When you click on the search icon, it should turn the bar into a search bar where the user can type in text. It hides the filter dropdowns.

Try it on the real hardware!

We have the NUC up and running now with its default POSM software, but we also have ssh access to it. Let's prove that we can deploy the app to that environment.

Add unit tests

We're test-less right now! Some unit tests would be nice.

Display story information from the database in the list

Right now we have just "Story Title" and "Description" in the view of the story list. Let's actually get the stories from the database to show in the list.

Build Point model

Name/Title
Story
Location
Region
Type of Place
Metadata
One to One Relationship with Story

[Server-side] Improve the messaging while the server is restarting

Any time the rails and nginx server restarts, the application is unresponsive for up to a minute or so. During this time, there's a completely unhelpful generic 502 error from nginx. Let's improve that by adding a customized error page that looks more like the login page or something at least branded with the Terrastories logo.

Bonus points if we can also include client-side polling against an /is_it_up endpoint and automatically redirect to the app once the server is running.

Set up a gem for handling geolocation data

We will ultimately need to get this back out as GeoJSON. Currently, the most promising gem for that is https://github.com/rgeo/rgeo-geojson, which suggests we'll want to use the rgeo gem as the basis for our Point models.