Please see EXPLORE TERRASTORIES for this.

We have a demo community to explore on our online server located at https://our.terrastories.app.

To access the demo community, log in with username terrastories-demo and password MapsThatRoar123*

Mapping Afro-descendant ancestral oral histories in Suriname

The Matawai Maroons, a community of descendants of formerly enslaved Africans who fought for their right to exist in the rainforest over three centuries ago, are mapping their ancestral homelands along the Saramacca River in Suriname and using Terrastories to overlay place-based oral histories with their maps. .

Traditional knowledge of water in Canada

The Haudenosaunee people at Six Nations Reserve in Ontario, Canada are using Terrastories to map traditional ecological knowledge and Indigenous stories of the Grand River along with scientific data about water quality.

It is possible to set a few theme properties for your community (logged in as an admin user).

Currently, there are only two options:

All content in this guide can be saved in PDF format or printed for use offline.

Save a PDF

To save a PDF, click on the Page actions menu to the right of a page title and select Export as PDF.

Choose one of the options from the Export as PDF window:

You might be wondering how you can get started using Terrastories, or just to try it out without committing to setting up your own Terrastories server.

Digital Democracy does maintain an online Terrastories server at . There are a number of Indigenous and other communities actively using this server. You can also explore any public-facing stories from this server at .

Currently, we don't have open registration to create your own account on this server, because we are paying for it, and we don't have a clear way to charge for usage (yet).

is an application for communities to map, protect, and share stories about their land.

It can be used by individuals or communities who want to connect audio or video content to places on a map. It is designed to be user-friendly and fun to interact with, allowing community members to freely explore without needing any technical background.

Terrastories began when a team of geographers from the Amazon Conservation Team and software developers from Ruby for Good decided to start building Terrastories to help a community in South America map their place-based oral histories. The Matawai Maroons of Suriname, a community of formerly enslaved Africans who fled into the forests over three centuries ago and reside there today, wanted to map oral histories about when their ancestors first arrived in these lands (). The community leaders were interested in having a tool that helps the young people get to know these places, their history, their culture, and who they are as a people.

Terrastories was built to accommodate that need, which the team also heard about from other communities across the globe.

To learn more about how Mapeo is currently being used, see .

Terrastories also comes bundled on . Please see the documentation for using Kakawa .

See additional information and troubleshooting steps for some common technical issues in the pages below:

• Offline map tiles are not showing up

• Saving and printing Terrastories reference materials

• Resetting passwords (using the Rails console)

The welcome interface for Explore Terrastories allows the user to browse and search for any community that has opted in to sharing their content with a greater public. You can either browse the list or search for the name of a community. You can also select a language on the top right of the window.

Once a community has been selected, you will view their map (without needing to log in!)

The Explore Terrastories interface offers a much streamlined and improved over what is offered in , and eventually we will adapt the main Terrastories interface to use the new framework and design of Explore Terrastories. That said, much of the functionality is the same, with a few differences:

The main sidebar now shows a more truncated, streamlined version of the content. Clicking on a story will open the full details of the story, with a much improved layout:

Information about Places now opens in the sidebar, too, giving users the ability to add more more information which previously was only shown in the popup on the map.

You can also filter Places using the dropdowns:

It is now possible to expand the image in the Place popup on the map, to view it in a higher resolution:

You can add multiple results to your filter in the secondary sidebar:

Lastly, you can toggle between communities! Once you have selected a community in the Welcome screen, you can then switch to a different community using the "Switch Communities" link in the bottom left of the sidebar:

Terrastories aims to be accessible to a wide range of communities in their native languages, and to facilitate the process of translating the app as needed.

Translation using Github

Currently, translations for Terrastories are handled through Github. In the future, we aim to use CrowdIn to make it easy for anyone to contribute translations to Terrastories for new or existing languages.

To begin translating, clone the Github Terrastories repository, and follow these steps.

1. Find the two or three-digit ISO language code for your language contribution

2. Navigate to the /rails/config/locales folder.

3. Copy the en folder (or any other language folder you want to use as your basis for translation) and rename it to your ISO language code. Also rename the en in each filename, and the beginning of each file, to your ISO language code.

4. Translate each string to your language of contribution.

5. Add your language to the languages list for all of the languages (in en.yml, pt.yml, mat.yml, ... and your new language contribution). You can use Google Translate to figure out how your language is translated in the other languages.

6. Submit your PR 🎉

Terrastories is a free and open-source application designed for communities to map, protect, and share place-based stories

Terrastories is a geostorytelling application built to enable Indigenous and other local communities to locate and map their own oral storytelling traditions about places of significant meaning or value to them.

Community members can add places and stories through a user-friendly interface, and make decisions about designating certain stories as private or restricted. Terrastories works both online and offline, so that remote communities can access the application entirely without needing internet connectivity.

***Support Limitation Warning***

1. It is not possible to self-host Terrastories, either online or offline, without assistance from a developer. This is due to maintenance issues on current dependencies in the codebase.

   • Documentation to guide someone executing these tasks is currently out of date.

   • We unfortunately are not able to offer this support to you.

2. For using Mapbox Studio maps on our.terrastories.app (or any Terrastories server), your maps need to be v2.x.x compatible. Please ask on the

About this Guide

This site provides an introduction to Terrastories and a collection of training & technical resources to support Terrastories users.

The site is divided into the following sections:

• Basic information about Terrastories, FAQs, how to get started, and our demo.

• Detailed instructions for using Terrastories, including the main interface, the member dashboard, and how to operate an offline Terrastories "Field Kit" once set up.

• Guides for the different ways that you can set up your own Terrastories server in different environments (online, offline "Field Kit", and community mesh network); about offline maps; about the super admin dashboard.

Use of this guide

Digital Democracy would like both Terrastories and the Terrastories reference materials we develop to help communities find ways to support autonomy, accessibility and collaboration in their projects. We know that people accessing this online resource will have diverse interests, goals, needs, and technical literacy. For this reason, there are a variety of paths to access information and levels of details users may be looking for. All pages in this guide can also be .

Feel free to make use of these resources under the creative commons license terms: .

Translation We strive to make our tools & resources accessible and available to communities in their local languages. If you'd like to contribute to translating this guide, please see the section on to learn how to get started.

Open Source Development

Terrastories and all of Digital Democracy's technical development is open source. Visit the section for more information.

Terrastories is a project currently being stewarded by Digital Democracy, a non-profit organization that partners with earth defenders to co-develop technology for social justice, together with a team of volunteer stewards. For more information on Digital Democracy, and how to support our user-centered co-development process visit .

The EXPLORE TERRASTORIES tool is a separate open-source application from the main Terrastories application, and requires a separate server setup. In short, Explore Terrastories queries a Terrastories server API which provides access to any unrestricted stories, which are the stories that may be accessed by a viewer role. (See Setting up users and roles for more information on roles and permissions).

Deployment

You can spin up your own Explore Terrastories server and set it up to work with your own Terrastories server API. The Terrastories server API is protected through a CORS policy, and you have to provide environmental variables in both the Terrastories server AND the Explore Terrastories server in order for your Explore Terrastories application to have permission to access the API. Please see for more information.

Explore Terrastories is a and there are instructions for how to set up your own Explore Terrastories server on the above-linked Github repository.

Create React App is a widely supported framework and there are detailed on how to deploy Create React App on many environments including AWS, Azure, Firebase, Github Pages, Heroku, Netlify, Vercel, and more.

Enabling access for communities

Once you have an Explore Terrastories server set up, you can enable communities to opt-in to using it by way of adding a public_communities feature flag. You can chose to enable it for your entire Terrastories server, a group of communities, or per each individual community.

For more information on how to do this, see.

Technical support

For help with common technical issues, see the section of this guide. For additional support, please check out the community of active users and maintainers of Terrastories on our public #terrastories channel on the .

If you're a developer or comfortable using GitHub, you can file an issue in the corresponding repository .

Terrastories works on a mini-computer, which transmits a WiFi signal that other devices can use to open the application. We call this a 🛖 Terrastories "Field Kit."

This is not a “real” WiFi signal that you can use to connect to the internet. Instead, it is an offline network, using which you can open Terrastories on your own device (phone, tablet, or laptop). Multiple devices can connect to and open Terrastories at any time.

All you need to do is turn on the mini-computer, connect to the WiFi, and you can start browsing Terrastories!

Are you interested in helping build Terrastories? We ❤️ contributors!

Terrastories is open-source, and contributions are welcome (we have had 90 folks contributing to the codebase, and that is not counting design work!) We could use Ruby on Rails, React, Mapbox/MapLibre, Docker, front-end, or UI/UX support, and our are indexed by priority and difficulty.

All of our developer onboarding documentation is on our Github.

Please see our , and read our guide for more information on Terrastories development.

Roadmap: to learn about current open source development work or where we're headed, check out our and our .

Community: join us

It may happen that a user is locked out of their community space because they lost their credentials; or, for your Terrastories server, you have lost the password to your super admin account.

Currently, there is no user interface to reset passwords, although we want to make it possible for super admin users to reset the password of a community admin user upon request.

It can be done using the , however.

Depending on your hosting environment, the way you access the Rails console may differ:

As an admin user, you can create, edit, and delete users that have access to your community in the Users view.

The Users view shows a list of all of the users that have access to your Terrastories community, and their respective level of access ("Role").

It may happen that when you have set up Terrastories for an offline environment ("Field Kit" or mesh) that your offline map tiles are not showing up on the Terrastories map.

Typically, there are two reasons for this:

1. Your map tiles are not properly defined in your style.json file. The mbtiles or pmtiles file must be defined in the sources array, and you must have layers which place and style your data (raster or vector) within the layers array. See for more.

Exploring, adding and editing stories

Upon entering the Stories view, you will first see a list of all of the stories that have been added to your community.

Story cards display the title, topic, language, permission level, description, location, and speakers for each story.

Click or press on one of the story cards to view more details for the story, including any media attachments (such as videos, audios or photos) and an inset map showing the location of the place associated with the story.

If you are an admin or editor user, you can also edit stories or create them.

For stories, the Topic and Language fields are made available as filter dropdowns on the Terrastories main interface.

For each story, you can set the Speakers and Places associated with that story. This is how you can create linkages between Speaker, Place, and Story data. You can also set the Permission Level to define which user role has access to the story.

Exploring, adding and editing speakers

Upon entering the Speakers view, you will first see a list of all of the speakers that have been added to your community.

Speaker cards display the name, photo, and speaker's community for each speaker.

Click or press on one of the speaker cards to view more details for the speaker, including any stories associated with them.

If you are an admin or editor user, you can also edit speakers or create them.

For speakers, the Speaker's Community field is made available as a filter dropdown on the Terrastories main interface.

Exploring, adding and editing places

Upon entering the Places view, you will first see a list of all of the places that have been added to your community.

Place cards display a photo, the location, the name, and a description for each place.

Click or press on one of the place cards to view more details for the place, including any stories associated with them, as well as an inset map showing the location of the place.

If you have any place name pronunciation audio recordings added for the place, a 🔊 icon will appear next to the name of the place. Clicking on this icon will play the audio.

If you are an admin or editor user, you can also edit places or create them.

For places, the Type of Place and Region fields are made available as filter dropdowns on the Terrastories main interface.

Places require latitude and longitude coordinates (in decimal degrees) to be added to the Terrastories map. Currently, these have to be added manually. In the future, we will make it possible to select places directly using a map, so you don't have to enter any coordinates.

Opting in to use, and configuring Explore Terrastories

To start using Explore Terrastories, you first have to opt in as a community admin to using it.

You will find settings for Explore Terrastories in the Settings menu for your community, under the heading "Public exploration of your community."

There are a few options here:

• Enable public interface: this check-box enables your Explore Terrastories view, which means it will show up on Explore Terrastories right away. Please ensure you are ready to go public before you enable this!

• About your community: this is a short description that will show up on the Welcome page of Explore Terrastories, and in the sidebar of your map when somebody first visits it.

• Display image or logo: you can upload an image or logo that will show at the top of the sidebar of your Explore Terrastories map.

Once you have enabled the public interface, you will be shown a direct URL for your Explore Terrrastories map that you can bookmark, embed, or share:

Selecting Stories to be show on Explore Terrastories

Explore Terrastories will show any of your community stories that have a Permission Level of anonymous:

Before you activate "Enable public interface", make sure you are sharing only the stories that you want to share by going through your Stories list, and ensuring that anything that should not be shown to the public is NOT set to an anonymous permission level. For more information on this, please see and .

One easy way to do this is by using the Stories Filter and setting Visibility to anonymous. That will show you only the stories that are going to be shown on Explore Terrastories, and you can edit the permission level for any of the ones you want to hide:

Terrastories has an import tool, which allows admin or editor users of a community to add stories, places, and speakers in one batch operation, rather than manually inputting them one by one. To access the import tool, navigate to the

For offline or mesh network usage, Terrastories can load a background map using a locally hosted map tileset and style, instead of a map from Mapbox Studio. This requires you to provide your own locally hosted map tiles and style.

By default, Terrastories provides a set of open-license offline map tiles, generated through the . These tiles cover the entire world, but are only compiled up to zoom level 8 (roughly the extent of a small country like Rwanda, Costa Rica, Slovenia or Bhutan). Once you zoom in past zoom level 8, no further level of detail will show.

However, you can also provide your own map tiles, which have to be in a or a format , alongside any map fonts (glyphs), sprites, and a style.json that defines how the map tiles will be visualized and styled on a map canvas.

How to generate or convert map tiles

Map tiles can be generated using existing utilities, or converted from standard geospatial data (Shapefile, GeoJSON), in several ways.

• Generate tiles using QGIS: The open-source GIS software QGIS has several tools for generating MBTiles in both raster and vector format. Generate XYZ tiles (MBTiles) can be used to create raster tiles of all of the content on your map canvas; this may also include XYZ Tiles from services such as OpenStreetMap, Bing, and Google Satellite. Generate Vector Tiles (MBTiles) can be used to create vector tiles from one or more vector layers. You can then further style these vector tiles in your style.json file.

  • The page in the Mapeo support materials has a visual, step-by-step guide for using QGIS to generate raster tiles.

Once generated, place the tiles in the map/data/ directory.

Compiling a custom style (style.json)

Map styles (per the style.json schema) defines the visual appearance of a map: what data to draw on the map canvas, the order in which layers are displayed, and how to style the data when drawing it. Mapbox provides a helpful with all of the possible style parameters, but it's generally useful to download an existing style.json file and modify it to suit your needs.

Using Mapbox (for vector)

One of the easiest ways to build a style.json file is by uploading and styling your data on and downloading the style.json file from there, in the following way:

• Design your map in Mapbox Studio. Mapbox provides extensive documentation and tutorials on using Studio .

• When you are done designing your map in the Mapbox Studio environment, click "Share" and then download the Map style ZIP file.

• Unzip the file, and extract the style.json and place it in tileserver/data/styles.

Importantly, the layer names referenced in styles and MBTiles have to match, in order for the tiles to receive a style property. It may be necessary to edit the layer names in style.json to reflect the names of the spatial data in the MBTiles file.

Raster tiles

If you have raster tiles that you want to load in Terrastories, those will need to defined differently from the vector tiles above. In sources, create a new source definition with url pointing to the raster MBTiles in the same format as above, and with type set to raster. Then, in layers, create a map object with your id of choice, type set to raster, and source set to the name of your raster tiles as defined in sources. Here is an example style.json file which only loads a raster MBTiles

If you want, you can add additional tile sources (vector as well as raster), and place your raster tile layer underneath vector layers. This is a good way to have an offline satellite imagery basemap with vector data (points, lines, polygons, and labels) overlaid on top of it.

Use a custom offline map package

Add your map package to the map/data folder. You can or download our default map package . Your map/data folder structure should look like:

Your style specification must include reference to the name of your style:

For more information on custom maps, please see the Github repository .

Use a custom Tileserver

If you are already hosting your own Tileserver, update compose.yaml file to remove the tileserver service and update the TILESERVER_URL to point to your hosted Tileserver:

Set up a custom Hostname

In order to access your Terrastories instance, you'll need to configure a domain.

You can setup our default terrastories.local, but you may also setup your own.

First, update your /etc/hosts file (you will need root/sudo write access), and add the following line:

Save and close.

If you utilized a custom domain (not terrastories.local), update your compose.yaml file:

About Terrastories

Overview

• ▶️ | Digital Democracy 2023 (documentary about an earth defenders retreat in Ecuador with testimonies about Terrastories) [EN]

• ▶️ | Indigenous Mapping Workshop 2021 (46-min video of a practical workshop) [EN]

• ▶️ | Indigenous Mapping Workshop 2020 (16 min-video) [EN]

• ▶️ | MozFest 2022 (7-min video) [EN]

• ▶️ | Code4Lib 2021 keynote (40-min video) [EN]

• 📖 Terrastories | published by Springer, 2023 [EN]

Examples of Terrastories projects

• 🌍 | Explore multiple communities worldwide that have opted to share some of their content with a greater public

• 📖 (case study) [EN / ES / PT / FR / KM / SW / TH / VI]

• 📖 [EN]

Other resources

• 📚 (a website that includes multiple guides, videos, case studies, etc.) [EN / ES / PT / FR]

• 📖 | The Amazon Conservation Team (guide, PDF) [EN / NL]

• 📖 | Ohneganos Ohnegahdę:gyo (guide, PDF) [EN]

This section provides guidance on how to use the main Terrastories interface, which is the interactive map and sidebar with place-based stories.

Table of contents:

• The Terrastories welcome page

The Terrastories welcome page

The first thing that you will be greeted with upon accessing Terrastories is the welcome page.

Currently, there are only a few things to do on the welcome page. What you can do depends on whether you are loading a Terrastories server that is online, or offline / hosted on a mesh.

For an online Terrastories server:

• You can log in with a username associated with a community.

• You can change the language to one of the translations supported by Terrastories. (This language will stay selected as you navigate across different views of the Terrastories application.)

• Coming soon: You will be able to access a list of public views for communities, which are views with a map and selected stories that communities have opted to share with a public without needing to log in.

For an offline Terrastories server:

• You can log in with a username associated with the community.

• You can enter the site without logging in, where you will be able to view unrestricted stories only.

• You can change the language to one of the translations supported by Terrastories. (This language will stay selected as you navigate across different views of the Terrastories application.)

Once you have logged in, or if you are offline, you will see an Enter Site button.

The main Terrastories interface is mobile and tablet accessible. Here is a screenshot of what the welcome screen looks like on a mobile phone (and also with Punjabi translation selected):

The Terrastories main interface

Once you have clicked or pressed on Enter Site via the Welcome page, you will arrive at the main Terrastories interface, which is composed of several elements:

• An interactive map, composed of both a background map and Storied Place Markers.

• On the left, a sidebar with a Story List composed of Story Cards, as well as Filter Dropdowns to filter content on both the Story List and the Storied Place Markers on the interactive map.

• On the bottom right, an introduction modal about Terrastories which can be closed.

The introduction modal can be closed, and the sidebar can be toggled to hide and show again using the ► button, to bring a full view to the interactive map.

The Terrastories main interface works in mobile as well. Currently, you can use the ► button on the left of the map, and the X button on the top right of the sidebar, to toggle between a full view of the two.

The content of stories in the Story List and Storied Place Markers are populated by data fields entered for stories, speakers, and places in the Terrastories member dashboard.

In the below screenshot, you can see the following data, from top to bottom:

For the Story card "Terrastories for the Matawai",

• Speaker photos associated with the story.

• Speaker names associated with the story.

• The story title

• Following the story, a 🔒 icon

For the Storied Place Marker "Pusugrunu village",

• Story name is shown in the popup header.

• A photo of the place.

• A place description.

• Region

If you have video recordings for a story in the Story List, there is a toggle available to set that video to full screen.

Interacting with the storied place markers and story list

There are several ways to interact with the stories and places on the Terrastories main interface.

You can:

• Scroll down the Story List in the sidebar to access all of the story content for the Terrastories community.

• Click or press on a Story Card, which will trigger the map to zoom to and center upon the Storied Place Marker, and open a popup for the place, associated with that story.

• Click or press on a Storied Place Marker, which will filter the Story List to only show stories associated with that place. The interactive map will also zoom to, and center upon, the maximum extent of the associated Storied Place Markers.

This screenshot shows a state of the Terrastories main interface where the "NatureBridge Campus" Storied Place Marker has been selected, and the Story List content in the sidebar has been filtered to only show one story associated with that place.

To use the filter dropdowns, first click or press on the first filter dropdown, which will show the following options. The options will only show if there is data entered for the story, speaker, and place fields in the Terrastories member dashboard:

• Language (for stories)

• Region (for places)

• Speaker (for speakers)

• Speaker's Community (for speakers)

Once you have selected an option in the first filter, the second filter will now show options for that first filter. The options will come from what has been entered in the Terrastories data for the fields in the first filter.

In this screenshot, "Type of place" has been selected for the first filter dropdown, and the second filter dropdown is showing all of the entries that have been entered for the "type of place" data field for places.

Selecting one of the options will filter Story Cards in the Story List, and Storied Place Markers on the interactive map, to only show data which has that option associated. For example, in this screenshot, if you select "village", the map will only show (and pan to) Pusugrunu, and the Story List will only show "Terrastories for the Matawai." You can try this out in the .

Additional features: 3d terrain view, and place name pronunciation

There are a few additional features on the Terrastories worth highlighting:

3d Terrain View (for online Terrastories): it is possible to enable a beautiful 3d terrain layer for your map (which users with an admin role for your community can do in ). This can really help bring storied places to life in regions with a topographically diverse landscape.

Place name pronunciation: we've heard from many Indigenous communities across the world that it would be helpful to have an audio feature where a native language speaker can add a clip of themselves pronouncing the name of the place. This is now active on Terrastories, as seen in this screenshot. Users with an admin or editor role can add audio recordings for places. For more information on how to do so, see .

The Terrastories map settings offer a set of controls for the background map behavior and default settings.

Currently, the map settings are accessed in the Theme view; in the future, we may move these into their own section.

Access the Theme view in the Terrastories member dashboard (as an admin user), and scroll down to Map Settings.

The Map Settings can be set either by manually entering values, or by interacting with the map on the Theme view. These are the different options available to you:

• Map bounds: the boundaries of the map which determine the extent to where you can scroll. This can be useful if you want to keep your community users focused on one geography. (This is particularly helpful for offline Terrastories servers with map tiles available only in a small part of the world, resulting in a blank map view elsewhere). By default, map bounds are deactivated; you must first toggle Allow unrestricted bounds to be able to set them.

• Map center: a latitude / longitude coordinate that determines the default starting position of your map.

• Zoom level: a zoom level determines how much of the world is visible on a map. Map zoom levels begin with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in). At low zoom levels, a small set of map tiles covers a large geographical area. At higher zoom levels, a larger number of tiles cover a smaller geographical area.

If you are setting up a map for a community in an online environment, you will see some additional options for Online Map Configuration.

• Mapbox Style URL: the Mapbox URL for the online Mapbox map that you want to use. This could be one of Mapbox's , or your own custom Mapbox map.

• Mapbox Access Token: a Mapbox access token to be used to validate your style. If you are supplying a custom style, it must be an access token that specifically has permission to access your style. To learn more about access tokens, see this .

• Activate 3D Terrain view: Mapbox provides a 3D Terrain service for any of their online maps to render the landscape in 3D. This can be a very nice feature for topographically device geographies. Be mindful that there is a tradeoff with performance, because the Terrain data takes some additional time to load. It is worthwhile to test the 3D Terrain view via the location most of your users will be accessing Terrastories, to ensure it makes sense to activate this feature for your users.

A Terrastories server can be hosted in a number of different environments, online and offline. We have developed workflows for several use cases that we have commonly encountered; however, as an application deployed using virtualization through Docker, there are numerous other ways that Terrastories may be hosted.

Currently, we have workflows, setup scripts, and documentation for the following four hosting environments:

• : It is relatively easy to deploy Terrastories online, as most web applications are created for online usage and so services like Heroku, DigitalOcean, and others are designed to easy online employment. We currently have instructions designed for Heroku (where Digital Democracy hosts the server) and hope to have instructions for other services soon.

• : For an entirely offline use case, we have a workflow where Terrastories can be set up a computer which serves the application through a hotspot. Other devices connected to that hotspot can then load Terrastories through the browser.

• 🍫 Hosting Terrastories on Kakawa (Earth Defenders Toolkit Offline): Terrastories also comes bundled on . Please see the documentation for using Kakawa .

To access the Terrastories member dashboard, you need to log in with credentials for a community that have either editor or admin access.

Once you have done so, you will see a link for Admin page (soon to be renamed "Member dashboard") on the welcome screen.

Click on that link to access the Terrastories member dashboard.

Upon accessing the member dashboard, you will be met with a message that you have signed in successfully. The default view that is shown is the Stories view.

You can access links to other views on the left side. Currently, these are:

• Stories: all of your community's stories.

• Speakers: all of your community's speakers.

• Places: all of your community's places. For more information about speakers, stories, and places, see .

• Users: the users that have access to your community, and their respective roles. See for more information.

• Theme: settings for your community theme, and map. See and for more information.

• Import: a dashboard for importing data in CSV format. See for more information.

• Language: a language selection menu where you can toggle between the different languages available in Terrastories. Hover over the acronyms to see the full name (in the language you have currently selected).

There is also a search bar at the top of the screen. Search for any term, and you will be provided results for any stories, speakers, and places that match the term:

This workflow is for hosting your own Terrastories server offline on a device like a mini-computer (NUC) running Linux.

The Terrastories "Field Kit" hosting environment is designed to allow one mini-computer device to serve Terrastories as an offline server accessible locally, or a mesh network. There are also some additional steps you can take to get the device to serve a hotspot through which other devices can get access to Terrastories. For more on how this works in practice, see Operating an offline Terrastories "Field Kit".

The way to set this up requires use of command-line shell (sometimes known as terminal). Fortunately, we've made it easy to go through most of the process by means of an easy setup script. For anyone wishing to go through the setup process in a more granular way, please refer to our .

Prerequisites

• Install Docker: To install Terrastories, your operating system first has to have Docker installed. The current version of Docker being used to deploy Terrastories as of February 2024 is v25.0.3.

• Install Docker Compose: You also need Docker Compose v2 (v1 will not work with our Docker files). The current version of Docker Compose being used to deploy Terrastories as of February 2024 is v2.24.5

Install Terrastories

To quick install Terrastories for offline usage, run the following command in the terminal:

This will download all of the appropriate Docker images and dependencies, and run through setting up Host domain and access at terrastories.local.

Or, instead of running this command, you can also choose to use Git to clone the repository locally to your computer. (Or, you can download the offline field kit as a ZIP file from to get the application.) And then, once in the directory, run bash install.sh.

Once you run the install script, you will be greeted with the following screen:

Press any key to start, and the script will install everything you need. Once complete, it will boot up your instance of Terrastories, which when completed will show the following on the terminal:

You can now access Terrastories in the browser at terrastories.local, where you will be greeted by the community setup screen:

Once you have set up a community, you may access the application, which will run with a default offline map:

If you want to use your own map, please see .

From here on, you can bring down your Terrastories instance by pressing Ctrl-C in the terminal. And you can run your Terrastories instance again at anytime using the following command (while in the directory):

Additional steps for configuration

There are a few additional steps needed to configure Terrastories for "Field Kit" usage that are not (yet) handled through the setup script. Note: the paths for these files may differ depending on operating system. These are the paths for Ubuntu 18.04 - 22.04.

Set a static IP

• Set up a static IP: using a text editor tool, edit /etc/NetworkManager/system-connections/Hotspot and under the ipv4 section, add the following line: address1=192.168.0.1/24

• Set this static IP address as host: using a text editor tool, edit /etc/hosts and change the IP address for terrastories.local to be the following: 192.168.0.1 terrastories.local

Make sure there are no other entries for terrastories.local

Configure your hotspot

First, you can create and turn on a Hotspot using the Linux operating system user interface. Modify the Hotspot name and password to be something easy to remember for anyone that is .

Next, you can make your Hotspot autoconnect on reboot by entering the following command in the terminal:

Install codecs to process H.264 videos

In our experience, NUC devices don't come bundled have the codecs to process H.264 videos such as mp4 files in the browser. Resolve this by installing ubuntu-restricted-extras in the terminal:

Bypass login screen on boot

For the workflow, it will be helpful to bypass the operating system login screen, since the device will be turned on without keyboard, mouse, or monitor. Here is a .

Set operating system to shutdown upon pressing power button

Similarly, for the , it will be helpful to set the operating system to bypass any logout screen and shut down right away upon pressing the power button, since the device will be operated without keyboard, mouse, or monitor.

In Ubuntu 18.04 or any similar Linux variants with acpi, use a text editor tool to create a file called /etc/acpi/events/power and enter the following in the content:

Save and close the file, and run:

Set operating system to start Docker on boot

Here is a , if needed.

Set Docker to operate without sudo access

Here is a , if needed.

Bringing Terrastories offline

You are now ready to bring Terrastories to an offline context!

From here, you can run the command:

And keep the service running. Every time that you shut down the machine, and turn it on again, Terrastories will restart by default, so you don't need to worry about any additional setup.

You may now proceed to show anyone administering the offline Terrastories "Field Kit" process the workflow for , which does not require any technical knowledge.

One Terrastories server can host multiple communities with their own maps and stories. The communities' data is protected and accessible only through their own user credentials.

To administer communities on Terrastories, there is a special administrative user that has the power to create and modify communities. We call this super admin. When logged in as super admin, you are not able to access or modify any community's data or maps; this user can only create and edit basic details of communities, as well as access generalized usage and data metrics.

Logging in as super admin

You can log in as super admin through the same login screen as for regular community users, accessible by navigating to the main Terrastories server URL (such as https://our.terrastories.app). If you are logged in as a community user already, you need to first log out.

Super admin dashboard

Once you have logged in with a super admin credential, you will access the super admin dashboard. At this time, there are only a few dashboard views available to super admins. The three that will be discussed in this guide are Metrics, Communities, and Features.

Metrics

The metrics dashboard provides an aggregate of all communities, stories, places, speakers, and users on the server. This can be used by the administrator of the server to keep track of, and report on, the data being provisioned by their Terrastories server.

Managing and creating communities

In the communities view, you can access a list of all of the communities using the Terrastories server, as well as when they were last updated - this means the last time any data changed on the community. There are filters available to sort the communities in alphabetical order by name, when they were first created, and when they were last updated.

By clicking on a community, you can access more information on the community, including individual metrics on stories, places, speakers, and users; and the usernames and their respective role (permissions) associated with them. In the future, we will make it possible for a super admin to help reset the password for a user that has lost them.

Creating a new community

From the community view, it is also possible to create a new community. The fields you can fill in are as follows:

• Name (required): the name of the community.

• Country: the country where the community is located. Currently, not being used anywhere in the Terrastories member dashboard or map.

• Locale: the language used by the community, by language ISO code (e.g. en, es, pt

Features: working with feature flags

In the Features view, we provide the option to add feature flags. Feature flags are a mechanism that we use to add new, custom, or beta features to a Terrastories server, before we make them available as a stable feature that you can toggle on and off.

You can add your own feature flags. They should be lower snake-case (e.g. cool_feature) and correspond to actual feature flags that are registered in Terrastories. Currently, one example is public_communities which is what controls the opt-in functionality for .

Once added, you can Enable / Disable the feature, and you can also turn it on for your entire Terrastorie server, or for selected groups of communities.

You can also Enable / Disable feature flags per each individual community:

Default super admin on a new Terrastories server

The default super admin credential on a new Terrastories server is terrastories-super with password terrastories. When you install Terrastories for the first time, you can log in with this username to set up the communities you will be hosting.

This workflow is for hosting your own Terrastories server online using Heroku and AWS.

To set up your own online Terrastories server, you need to have the following in place:

• A fork of the Terrastories application on Github which is what you will deploy as your Terrastories server application.

• A Mapbox account access key and default map style to use for new communities that you set up on your server.

• A cloud storage bucket to store media content uploaded to Terrastories.

• A cloud application platform account to host and run the Terrastories application.

Currently, Terrastories is set up to work with Amazon AWS S3 cloud storage buckets, and the Heroku web application platform. The following workflow describes how to set up an online Terrastories server using these two services; however, it should be possible to deploy Terrastories using other services as well, but it may require further customizing Terrastories to work with those services. (There is already some scaffolding for using services like Azure in the Terrastories Rails file)

1. Fork the Terrastories repository on Github

On Github, fork the Terrastories repository master branch at to your own account. This codebase is what will be deployed on your online Terrastories server. You can make any customizations that you want (or create branches), but it is recommended that you keep your fork up-to-date with the Terrastories master codebase.

2. Set up a Mapbox account and get access token and a map style URL

Terrastories uses Mapbox.com as the background map when set up online. You will need an access token associated with your account, as well as a URL to your map style of choice. These will be provided as a default for communities created on your Terrastories server. Once a community has been set up, the community administrator can then change the Mapbox map URL and access token via the Themes settings.

If you haven’t already done so, sign up for a Mapbox account at and copy down your access token, along with a map style URL of your choice. You will need these later when setting up Heroku.

3. Set up an Amazon AWS S3 bucket

On Amazon’s AWS website at , sign up for an account and make your way to the Amazon S3 section of the web console. If you are not familiar with Amazon S3, please check out Amazon’s guide.

Create a bucket for storing data in S3. Depending on your use case, the properties here may vary, and you should be careful in ensuring that your bucket is sufficiently secure in your local context. We recommend the following:

• Block all public access (bucket settings)

• Set up an access control policy, or grantee with list/read/write access

• Data encryption

Copy down the following information for your bucket, as you will need it later when setting up Heroku:

• AWS Bucket Region

• AWS Bucket Name

• AWS User Access Key

• AWS User Secret Access Key

AWS Pricing is calculated per the resources used. For Terrastories, this will mainly be storage, and requests & data retrievals. As of early 2022 the are very low, with storage estimated to be $0.023 per GB per month, for buckets under 50 TB. This is the only necessary cost associated with hosting Terrastories online – there are free tiers available for all other services (Mapbox, Heroku).

4. Set up a Heroku account

Navigate to and sign up for an account. As of December 2022, this needs to be a Hobby account ($7/month), or higher to improve your server’s performance and security (SSL).

Create a new app with your name of choice, and optionally add it to a pipeline if you plan to do staging (i.e. with a development and production server).

In the Deploy section, connect the app to Github, and find your forked Terrastories repo to connect.

In the Resources section, add a Heroku Postgres add-on. For an experimental online Terrastories servers, the Mini plan ($0.01/month) might be sufficient, or you could upgrade to a Basic plan $9/month). Check the Heroku database pricing guidelines for more information on your needs.

In the Settings section, you need to add some environmental Config Vars. Provision the following:

Next, in the Settings section, add the following two buildpacks (in this order):

• https://github.com/timanovsky/subdir-heroku-buildpack

• heroku/ruby

Optionally, in the Settings section, set up an SSL Certificate and a Custom Domain. This is recommended for any public-facing servers, to ensure that the data will be kept secure, and also to have a URL hosted on your own domain (i.e. something like terrastories.yourwebsite.com).

Lastly, as of March 2022, currently Heroku apps with a heroku-20 stack are not deploying Terrastories due to our Ruby dependency being out of date. For the time being, you need to downgrade the Heroku stack to heroku-18 by installing the on your system and running the following command: heroku stack:set heroku-18 -a your-app-name. However, we hope to have our stack upgraded to work with heroku-20 by early 2023.

Now you are ready to deploy. In the Deploy section, choose the branch that you want to deploy, either via Automatic Deployment or Manual.

Once you have successfully deployed, one task remains: seeding the database so you can access the Terrastories super admin to start creating communities. To do this, click on the More button on the right right and then Run Console. Enter the following command: rake db:seed. Once that finishes, your app should be all set up. You can find the URL of your Terrastories server in the Settings section in Heroku.

Explore Terrastories is an extension of the main Terrastories application. It is a tool that community users of Terrastories may opt in to using, in order to share to a selection of their place-based stories with a broader public.

Since the very beginning, because of the sensitive nature of place-based oral histories and all other forms of knowledge tied to land, Terrastories has always considered security and data protection as very important concerns in the ways that the content is accessed, and therefore access had to be protected by way of requiring everyone to log in.

However, many communities do want to share some of their content with a greater public. Explore Terrastories provides them with an easy way to do so, and for an interested public to be able to peruse the stories of a range of communities that have opted in.

❤️ The creation of Explore Terrastories was funded via an American Rescue Plan grant by the . We are grateful for their support.