# Introduction
## 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.

Terrastories as used by the Haudenosaunee community at Six Nations of the Grand River Reserve in Ontario, Canada to map traditional knowledge and creation stories.

## \*\*\*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 [Mapbox Discord](https://docs.mapbox.com/help/faq/mapbox-developers-discord/) for assistance. 3. Feature development is on hold for the foreseeable future. ## 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: * [OVERVIEW](/overview/about-terrastories)\ Basic information about Terrastories, FAQs, how to get started, and our demo.
* [USING TERRASTORIES](/using-terrastories/exploring-the-terrastories-main-interface)\ Detailed instructions for using Terrastories, including the main interface, the member dashboard, and how to operate an offline Terrastories "Field Kit" once set up.
* [SETTING UP A TERRASTORIES SERVER](/setting-up-a-terrastories-server/hosting-environments)\ 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.
* [EXPLORE TERRASTORIES](/explore-terrastories/what-is-explore-terrastories)\ An overview of the Explore Terrastories application, including how to set it up and configure for usage, and how to use it once set up.
* [MISCELLANEOUS](/miscellaneous/support)\ Other pages on support, troubleshooting, translation, additional references, information for developers, and more. ### 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 [saved in PDF format and printed for use offline](/miscellaneous/troubleshooting/saving-and-printing-terrastories-reference-materials). *Feel free to make use of these resources under the creative commons license terms:* [Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/). **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 [Translating Terrastories](/miscellaneous/translating-terrastories) to learn how to get started. #### Open Source Development Terrastories and all of Digital Democracy's technical development is open source. Visit the [FOR DEVELOPERS](/miscellaneous/for-developers) 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* [*our website*](https://www.digital-democracy.org)*.*

Terrastories watercolor by Jennifer Lu, made on the occasion of Ruby by the Bay 2019.

# About Terrastories [Terrastories](https://terrastories.app/) 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 ([read more about the Matawai and their story here](https://www.earthdefenderstoolkit.com/community/place-based-storytelling-with-the-matawai-in-suriname/)). 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 [How Terrastories is being used](/overview/about-terrastories/how-terrastories-is-being-used).
## **Key features of Terrastories** * **Interactive user interface**\ Terrastories was specifically created with the youth of earth defender communities in mind, and it is designed to be educational about land, history and culture while also engaging and fun to play with. Teachers may use Terrastories as part of their curriculum to help young people bolster their computer literacy and skills while also learning about their community’s stories.
* **Privacy & sharing**\ Security and data protection are very important concerns for many earth defender communities. Depending on your particular needs, you may want to keep all or certain parts of your map from falling into the wrong hands. Terrastories was built with this concern in mind, and enables communities to designate certain stories as private and restricted. This means that you need to have special log-in credentials to see those stories. By contrast, there might be stories that your community wants to share with the world, and you can set those to be viewable by anyone.
* **Works in completely offline environments**\ Many earth defender communities reside in remote contexts, with limited or no access to the internet. Unfortunately, many storytelling and mapping tools require internet access, and won’t work (or barely work) without it. For those reasons, Terrastories was built to work offline. The entire application can be run on a computer or a device that transmits a WiFi hotspot through which other devices can connect. In addition to ease of use, some communities appreciate this function for data privacy reasons: storing the maps and stories on a physical device helps ensure that private data does not leave the territory.
* **Highly customizable**\ Much of the Terrastories app is customizable in terms of language, maps, and information you collect. When you download it, it comes with a standard online map of the world, but you can choose to use your own map, including one that can work offline. You can also translate Terrastories into your own language, and set up story filters based on your own taxonomies and categories for places in your lands. # How Terrastories is being used A selection of interesting use cases by communities across the globe. **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. [Read more](https://www.amazonteam.org/maps/lands-of-freedom/). **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. [Read more](https://terrastories.io/from-the-amazon-to-the-great-lakes-sharing-knowledge-and-mapping-oral-histories-with-first-nations-communities-in-canada/). #### Indigenous Wayana lands in Suriname
> The Wayana Indigenous community in Suriname is using Terrastories to map oral narrations from elders about special places and the Wayana boundary agreements with neighboring communities. [Read more](https://terrastories.app/wayana-community-in-suriname-uses-terrastories-as-part-of-their-mapping-project/). #### Ogiek ancestral lands along Mount Elgon in Kenya
> The Ogiek of Mount Elgon are using Terrastories to map stories about sacred caves, place names, and more. #### Dakota storytelling in the United States
> The Dakota community of Sisseton Wahpeton Oyate is using Terrastories to map sacred stoires of the landscape. # FAQs {% hint style="info" %} For help with technical issues using Terrastories, see the [Troubleshooting](/miscellaneous/troubleshooting) and [Support](/miscellaneous/support) sections. {% endhint %} * [Who made Terrastories? ](#who-made-terrastories) * [Is Terrastories free to use? ](#is-terrastories-free-to-use) * [Where can I check out Terrastories in action?](#where-can-i-check-out-terrastories-in-action) * [How do you install Terrastories? ](#how-do-you-install-terrastories) * [What is the difference between Terrastories and story maps? ](#what-is-the-difference-between-terrastories-and-story-maps) * [Is Terrastories a data collection tool? ](#is-terrastories-a-data-collection-tool) * [What kind of data does Terrastories work with? ](#is-terrastories-a-data-collection-tool) * [What languages is Terrastories available in? ](#what-languages-is-terrastories-available-in) * [How does Terrastories work offline? ](#how-does-terrastories-work-offline) * [Who will have access to my data? ](#who-will-have-access-to-my-data) * [Can you help me deploy Terrastories? ](#can-you-help-me-deploy-terrastories) * [How can I report bugs or problems using Terrastories?](#how-can-i-report-bugs-or-problems-using-terrastories) ## Who made Terrastories? Terrastories was built by a volunteer team of open-source stewards and a community of developers, in close collaboration with Indigenous partners and allied NGOs. Terrastories was conceived in 2018 by geographers from the [Amazon Conservation Team](https://amazonteam.org) when working with the [Matawai](https://amazonteam.org/maps/lands-of-freedom), an Afro-descendant Maroon community in Suriname, and was first built by [Ruby for Good](https://rubyforgood.org), a volunteer collective of Ruby developers. Since then, numerous open-source volunteers have contributed to Terrastories, and several organizations and foundations have made small grants to Terrastories including Tech Matters and the Association for Tribal Archives, Libraries, and Museums (ATALM). Currently, Terrastories is being stewarded and maintained by Digital Democracy and a team of open-source stewards. Active stewards include Rudo Kemper, Laura Mosher, Albert Chae, and Luandro Vieira. Digital Democracy is a non-profit organization that works in solidarity with marginalized communities to use technology to defend their rights. For more information on Digital Democracy and our partners, visit [our website](https://www.digital-democracy.org). We would like to acknowledge a past team of stewards who were pivotal to the early success of Terrastories, including: Miranda Wang, Kalimar Maia, Jason Hinebaugh, Ian Norris, and others. ## Is Terrastories free to use? Yes, Terrastories is free to install and use, and our [license](https://github.com/Terrastories/terrastories/blob/master/LICENSE) permits open modification and distribution. ## Where can I check out Terrastories in action? There are two ways to check out Terrastories in action. You can explore the main application (both the front-end map and the content management system) by logging in to the [Terrastories demo](/overview/terrastories-demo). You can also explore a number of communities that have opted in to share some of their content with a greater public on :earth\_africa: [**Explore Terrastories**](https://explore.terrastories.app/). ## How do you install Terrastories? Terrastories is a web application that you can host online, offline, or on a mesh network. For more information on hosting, please see the **Setting up a Terrastories Server** section (starting with [Hosting environments](/setting-up-a-terrastories-server/hosting-environments)). Digital Democracy also maintains an online Terrastories server at . If you would like to request a community account on our server, please [write to us](mailto:info@digital-democracy.org). ## What is the difference between Terrastories and story maps? Today, there are numerous tools that can be used for sharing stories with interactive maps; for example, ArcGIS StoryMaps, Mapbox's Storytelling template, StoryMaps.JS, Leaflet Storymaps, and more. The biggest difference between Terrastories and these tools is that **Terrastories is built for mapping and maintaining a database of place-based stories, whereas these other tools are more designed for telling stories using an interactive map.** There are several other key differences between Terrastories and these applications: 1. Terrastories has a content management system (called member dashboard) for easily managing and determining access for mapped content. 2. Terrastories can easily work offline, whereas most of these tools either require internet access or technical expertise for offline setup. 3. Terrastories has a system of granular permissions that can be used to restrict access to sensitive content. ## Is Terrastories a data collection tool? Terrastories can be better understood as a content management system and a visualization tool than a data collection tool. If you have access to a Terrastories server (online or offline), you *could* directly enter data about Places, Stories, and Speakers via the Terrastories administrative menu on both mobile devices and desktop computers, but it's worth stressing that there are better and more bespoke tools for this kind of work. It's also not possible to capture audio, video, or images through the Terrastories user interface at this time. We recommend using Terrastories in tandem with another tool for data and story collection and capture. You could use [Mapeo](https://mapeo.app) (or any other mapping tool on the Earth Defenders Toolkit [Toolfinder](https://earthdefenderstoolkit.com/toolfinder)) for mapping places, and any device audio / video recording tool for capturing stories. These can then be entered into Terrastories (either one-by-one, through the Terrastories import feature, or using the [Mapeo Observations to Terrastories Places](https://docs.earthdefenderstoolkit.com/device-usage/bundled-applications/mapeo-data-hub/mapeo-observations-as-terrastories-places) workflow in *Kakawa* (the offline Earth Defenders Toolkit build) There is also an [ODK / KoboToolbox survey form](https://terrastories.app/now-available-an-odk-kobotoolbox-form-to-collect-places-and-stories-for-terrastories-in-the-field/) available that is designed to gather all of the data required by Terrastories, including multiple Stories and Speakers per place, photos, audio, and video. ## What kind of data does Terrastories work with? There are three kinds of data in Terrastories: `stories`, `places`, and `speakers`. Each have a series of fields you may fill in, and you can also attach media attachments specific to each data type. In addition to text fields, `places` also have latitude and longitude fields which are used to place stories on the map. For more information on Terrastories data, see [Exploring and creating stories, speakers, and places](/using-terrastories/using-the-terrastories-member-dashboard/exploring-and-creating-stories-speakers-and-places). ## What languages is Terrastories available in? Currently, Terrastories is available in Amharic, English, Spanish, Hindi, Japanese, Matawai, Dutch, Portuguese, Punjabi, Swahili, and Chinese (Mandarin). Terrastories can be translated into additional languages on Github. For more information, see [Translating Terrastories](/miscellaneous/translating-terrastories). ## How does Terrastories work offline? Terrastories is a web application that can be hosted online or offline. The Terrastories codebase comes equipped with everything you need for the application to work offline, including a default offline map tileset if you need it. When installed for offline usage, Terrastories may be run through the browser much like an online website. It may be accessed at the URL `terrastories.local` (or a custom path if set up). You just need to be connected to the device hotspot (if it is a "Field Kit" setup), or the community mesh network. ## Who will have access to my data? Terrastories is built so you can control who has access to your data. You can restrict access to your stories by setting them to only be viewable by community members, editors, or admins. For more about this, see [Setting up users and roles](/using-terrastories/using-the-terrastories-member-dashboard/setting-up-users-and-roles). You can also set your community to be viewable by the public, or not. If there *is* a public view, only unrestricted stories are shown, and you can ensure that the background map is different from your community view. For more about this, see [Setting up an Explore Terrastories view for your community](/using-terrastories/using-the-terrastories-member-dashboard/setting-up-an-explore-terrastories-view-for-your-community). Lastly, the *super admin* of a Terrastories server does not have access to your data. Through the [Navigating the Super Admin dashboard](/setting-up-a-terrastories-server/navigating-the-super-admin-dashboard), a Terrastories *super admin* may view some basic metrics about your community like how many stories, places, and speakers have been created, and the last time the community has had some activity; but the data itself is not accessible to the *super admin*. ## Can you help me deploy Terrastories? There is a community of active users and maintainers of Terrastories that participate in our public #terrastories channel on the [Ruby for Good Slack](https://rubyforgood.slack.com/join/shared_invite/zt-1kfeimohe-KL~~~6Lkof7G94_7Ojd_Hw#/shared-invite/email) and on our [Earth Defenders Toolkit Forum](https://forum.earthdefenderstoolkit.com/). We encourage you to consult these spaces for additional tips and ideas on how people are using Terrastories. Digital Democracy's core team is very small and we have limited capacity to provide direct accompaniment for implementing Mapeo outside of our existing partnerships. In some cases we are able to offer support. To read more about the way we work with partners and different levels of support, see [here](https://drive.google.com/file/d/1c9C1-6v1EHKnfrYDsBn3VNu5qS_pUNMC/view?usp=sharing). ## How can I report bugs or problems using Terrastories? There is community of active users and maintainers of Terrastories that participate in our public chat channel on Slack. To join the conversation or seek help on technical issues, you can the public #terrastories channel on the [Ruby for Good Slack](https://rubyforgood.slack.com/join/shared_invite/zt-1kfeimohe-KL~~~6Lkof7G94_7Ojd_Hw#/shared-invite/email). # Getting started {% hint style="info" %} Before getting started working with Terrastories, you may want to first check out the [Terrastories demo](/overview/terrastories-demo) and the [FAQs](/overview/faqs). {% endhint %} 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 [**our.terrastories.app**](https://our.terrastories.app). 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 [**explore.terrastories.app**](https://explore.terrastories.app/). 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). If you would like to request a community account on our server, even if just to try out the application, please [write to us ](mailto:info@digital-democracy.org)and briefly let us know how you plan to use the online server. We'd be happy to create an account for you.

Login screen at https://our.terrastories.app

# Terrastories demo {% hint style="info" %} **New**: you can also explore Terrastories freely at our :earth\_africa: [**Explore Terrastories**](https://explore.terrastories.app/) server, without needing to log in. {% endhint %} We have a demo community to explore on our online server located at [**https://our.terrastories.app**](https://our.terrastories.app/). To access the demo community, log in with username **terrastories-demo** and password **MapsThatRoar123\***
{% hint style="info" %} *All of the screenshots in the* [USING TERRASTORIES](/using-terrastories/exploring-the-terrastories-main-interface) *section were captured from this demo community.* {% endhint %} # Exploring the Terrastories main interface 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 Terrastories main interface](#the-terrastories-main-interface) * [Interacting with the storied place markers and story list](#interacting-with-the-storied-place-markers-and-story-list) * [Additional features: 3d terrain view and place name pronunciation.](#additional-features-3d-terrain-view-and-place-name-pronunciation) {% hint style="info" %} For guidance on navigating the Terrastories member dashboard, please see [Using the Terrastories member dashboard](/using-terrastories/using-the-terrastories-member-dashboard). {% endhint %} ## 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. {% hint style="info" %} In addition, if you have logged with a username with an appropriate role level, you will see a link to the **Admin Page** (soon to be renamed "Member Dashboard"). \ \ In the remainder of this page, we will cover only the main Terrastories interface. For instructions on using the Member Dashboard, please see [Using the Terrastories member dashboard](/using-terrastories/using-the-terrastories-member-dashboard). {% endhint %}
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. * On the top right, an **inset mini-map**, and **map controls** for returning to the default map center and zoom level, zooming in and out, and changing and the map pitch.
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** which indicates that this is a restricted story, and you have access because of your user role which has permission to view it. * A **story description** * **Media attachments** for the story (in this case, a video). * Although it is not visible in the screenshot, below the media attachments there will also be the **language** of the story, if provided. For the Storied Place Marker "Pusugrunu village", * **Story name** is shown in the popup header. * A **photo** of the place. * A **place description**. * **Region** for the place. * **Type of place** taxonomy for the place.
{% hint style="info" %} To learn more about the data fields for stories, speakers, and places, please see [Exploring and creating stories, speakers, and places](/using-terrastories/using-the-terrastories-member-dashboard/exploring-and-creating-stories-speakers-and-places). {% endhint %} 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. * Use the **Filter Dropdowns** to filter content in both the Story List, and Storied Place Markers on the interactive map. The interactive map will also zoom to, and center upon, the maximum extent of the filtered 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) * Topic (for stories) * Type of Place (for places)
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 [Terrastories demo](/overview/terrastories-demo).
## 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 [Modifying map settings](/using-terrastories/using-the-terrastories-member-dashboard/modifying-map-settings)). 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 [Exploring and creating stories, speakers, and places](/using-terrastories/using-the-terrastories-member-dashboard/exploring-and-creating-stories-speakers-and-places).
# Using the Terrastories member dashboard 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* [Exploring and creating stories, speakers, and places](/using-terrastories/using-the-terrastories-member-dashboard/exploring-and-creating-stories-speakers-and-places).
* **Users**: the users that have access to your community, and their respective roles. \ *See* [Setting up users and roles](/using-terrastories/using-the-terrastories-member-dashboard/setting-up-users-and-roles) *for more information.*
* **Theme**: settings for your community theme, and map.\ *See* [Customizing your community theme](/using-terrastories/using-the-terrastories-member-dashboard/customizing-your-community-theme) *and* [Modifying map settings](/using-terrastories/using-the-terrastories-member-dashboard/modifying-map-settings) *for more information.*
* **Import**: a dashboard for importing data in CSV format.\ *See* [Importing data](/using-terrastories/using-the-terrastories-member-dashboard/importing-data) *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:
# Exploring and creating stories, speakers, and places {% hint style="info" %} Adding and editing Terrastories data requires `admin` or `editor` access. If you are logged in as a `member`, you will only be able to explore stories, speakers, and places. As a `viewer` member, you can not access these views. {% endhint %} ## 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.
{% hint style="info" %} A Story must have at least one Speaker and at least one Place selected to appear on the Terrastories main interface. {% endhint %} ## 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.
{% hint style="info" %} A Speaker must have at least one Story associated with them to appear on the Terrastories main interface. {% endhint %} ## 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. {% hint style="info" %} To get coordinates in Decimal Degrees for Terrastories places, there are couple of different ways: * You can use [Bing Maps](https://www.bing.com/maps). Right-click on a location on the map, and at the bottom of the popup you will be able to copy & paste the coordinates in decimal degrees. (You can use Google Maps as well, but you have to left-click twice on the map and manually copy & paste the coordinates, which is not as easy.) * You can get coordinates from GIS data, if you or someone working with you is using GIS software like QGIS, ArcGIS, or Google Earth Pro. * You can get coordinates from a hand-held GPS device, or a smartphone mapping application such as [Mapeo Mobile](https://mapeo.app). {% endhint %}
{% hint style="info" %} A Place must have at least one Story associated with it to appear on the Terrastories main interface. {% endhint %} # Customizing your community theme {% hint style="info" %} Customizing your community theme requires `admin` access. If you are logged in as an `editor`, `member`, or `viewer`, you will not be able to access this settings menu. {% endhint %} It is possible to set a few theme properties for your community (logged in as an `admin` user). Currently, there are only two options: * **Welcome Screen:** you can set a background image for your welcome screen, once a user has logged in. * **Sponsor Logos**: you can add one or more logos to display on the welcome screen, once a user has logged in. These could be for your community, organization, sponsors, donors, or anything else. In the future, we may make it possible to set more thematic properties for your community, such as color scheme. If you have ideas for feasible ways to allow users to modify their community theme, please [let us know](https://github.com/Terrastories/terrastories/discussions).
# Setting up users and roles {% hint style="info" %} Managing users requires `admin` access. If you are logged in as an `editor`, `member`, or `viewer`, you will not be able to access this settings menu. {% endhint %} 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"). There are currently four **Roles** for a Terrastories community: 1. `admin` - has permission to view, add, or edit data (restricted and non-restricted); add or edit users; and change Theme settings. 2. `editor` - has permission to view, add, or edit data (restricted and non-restricted). 3. `member` - has permission to view data (restricted and non-restricted). 4. `viewer` - has permission to view data (non-restricted only).
There are several fields you can fill out for a User. * The ones that are required are **Username**, **Password** and **Role**. * The user's **Display Name** and **Photo** are currently only used in the content management system and a few areas on the main application, but we may start to use these more in the future. * It is also recommended setting an **Email** as we may make it possible in the future to permit users to recover their password if they've lost it.
# Setting up an Explore Terrastories view for your community Please see [EXPLORE TERRASTORIES](/explore-terrastories/what-is-explore-terrastories) for this. # Modifying map settings {% hint style="info" %} Customizing map settings requires `admin` access. If you are logged in as an `editor`, `member`, or `viewer`, you will not be able to access this settings menu. {% endhint %} 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. * **Pitch degree:** the camera's pitch is the visual tilt of the map, which is determined by the angle towards the horizon measured in degrees. A pitch of 0 results in a two-dimensional map, as if your line of sight forms a perpendicular angle with the earth's surface, while a greater value like 60 looks ahead towards the horizon. * **Bearing degree:** a bearing is the direction you’re facing, measured clockwise as an angle from true north on a compass. This can also be called a heading. In this system, north is 0, east is 90, south is 180, and west is 270. For the map, the bearing rotates the map around its center the specified number of degrees. * **Set projection for map:** A map projection is a way to flatten the planet's surface onto a page or screen. Every projection has strengths and weaknesses, so the right projection depends on your use case. To learn more about the available map projections in Terrastories, visit Mapbox's [guide to projections](https://docs.mapbox.com/mapbox-gl-js/guides/projections/). {% hint style="success" %} If you are not able to use the inset map on the Map Settings block of the Theme view to set center, zoom and other properties, and have access to the internet, you could use Mapbox's [Location Helper](https://demos.mapbox.com/location-helper/) tool instead.\ \ This may be helpful if you are trying to set up offline map tiles, but your map is blank because you are not zoomed in enough on the right area for them to show up. {% endhint %} 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 [default public styles](https://docs.mapbox.com/api/maps/styles/), 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 [Mapbox guide](https://docs.mapbox.com/help/getting-started/access-tokens/). * **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. {% hint style="info" %} If you do not see the Online Map Configuration options, then you are working with Terrastories set up for an offline or mesh environment. See [SETTING UP A TERRASTORIES SERVER](/setting-up-a-terrastories-server/hosting-environments) for more details. {% endhint %}
# Importing data {% hint style="info" %} Importing data requires `admin` or `editor` access. If you are logged in as a `member` or `viewer`, you will not be able to access this settings menu. {% endhint %} 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 **Import** view in the sidebar. On this view, you can import data for Places, Speakers, and Stories, and this can be done in one operation (or one by one, as you prefer).
Currently, the Terrastories import tool can interpret a `csv` file. You can either **Download a Sample CSV** file that is provided by Terrastories (online or offline), or you can use your own `csv`. For Terrastories in an offline environment, it is possible to upload media attachments as well. See the below section [Importing media attachments (Terrastories in an offline or mesh hosting environment only).](#importing-media-attachments-terrastories-in-an-offline-or-mesh-hosting-environment-only) ### Importing CSV files To begin using the import tool, click **Choose File** and select your `csv` for any of the data types (Places, Speakers, or Stories). The columns in your `csv` file can be in any order. Once you've uploaded your `csv`, the Terrastories import tool allows you to map your columns the Terrastories data fields. For any data fields for which there is no column in your `csv` to match, you can just leave that blank. {% hint style="info" %} The `Media` and `Name audio` fields are intended for media attachments, and currently will not work for Terrastories hosted in an online environment. {% endhint %}
Once you are done, click **Import**. The data will now be added to Terrastories. {% hint style="info" %} Make sure to provide names for each column in the top row of your `csv` so you can map the columns to the Terrastories data fields, as in the screenshot above. {% endhint %} {% hint style="warning" %} Depending on the size of your `csv` (and media attachments if adding for an offline or mesh environment), the importing process may take a while. Do not close the page while this process is ongoing or your import operation will be interrupted. {% endhint %} ### Importing media attachments (Terrastories in an offline or mesh hosting environment only) For a Terrastories community on a server that is hosted in an offline or mesh environment, it is possible to add media attachment for each of the Stories, Places, and Speakers being imported. Media attachments include photos, videos, and audio. (In the future, we hope to make this possible for Terrastories hosted in an online environment as well.) The way this works is that for each row in the `csv`, if there is a filename listed in the `media` or `name audio` fields being imported, then it will look for that filename in the `/rails/import/media` directory of your Terrastories application. If it finds the file, then it will import it for the data row you are importing; if not, it will skip adding a media attachment. For example, let's say that you have a story in your `csv` called **My Terrastories Story**, and you want to add a video file called **TerrastoriesVid\_Final.mp4**. 1. First, copy your file **TerrastoriesVid\_Final.mp4** to the `/rails/import/media` directory. 2. Next, find the row containing your story **My Terrastories Story** in your `csv`. Ensure that there is a column in which the full filename is written out (e.g. **TerrastoriesVid\_Final.mp4**, with the `.mp4` file type and matching the capitalization of your file). 3. When you click **Import** to import the `csv`, and the tool starts to import your **My Terrastories Story** row, it will look for a file called **TerrastoriesVid\_Final.mp4** in `/rails/import/media`. Since you placed it there, it successfully locates the file, and proceeds to add the file as a media attachment. The same will happen for all of your `csv` rows for any Stories, Speakers, and Places that you import, in one batch operation. {% hint style="info" %} If one of your rows failed to attach a media file, then it is likely that the filename was misspelled in the `csv`. It is easy to miss a character or capitalization. It can also sometimes happen that a filename ends in all capital letters such as **.MP4**. Make sure the filenames strings in your `csv` match the files exactly. {% endhint %} # What is Explore Terrastories? **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. {% hint style="info" %} Read more about Explore Terrastories in this article "[Explore Terrastories! Local stories for a wider public](https://terrastories.app/explore-terrastories-local-stories-for-a-wider-public/)" by María Alvarez Malvido. {% endhint %}

Welcome screen of Explore Terrastories, showing the ability to browse and search maps and stories of communities that have opted in to participate.

:heart: *The creation of Explore Terrastories was funded via an American Rescue Plan grant by the* [*Association of Tribal Archives, Libraries, and Museums (ATALM)*](https://atalm.org/)*. We are grateful for their support.* # Exploring the Explore Terrastories interface 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!)
{% hint style="info" %} Note: Explore Terrastories shows the same default basemap for all communities. This is done in order to protect any sensitive information that may be added to a community's custom map. In the future, we will make it possible for communities to select their own custom map for their Explore Terrastories view. {% endhint %} The Explore Terrastories interface offers a much streamlined and improved over what is offered in [Exploring the Terrastories main interface](/using-terrastories/exploring-the-terrastories-main-interface), 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:
# Setting up Explore Terrastories for your community {% hint style="info" %} This page is intended for communities who have an account on a Terrastories server that also has an Explore Terrastories server set up. For example, the [**our.terrastories.app**](https://our.terrastories.app/) server is allowing communities to opt in to using Explore Terrastories at [**explore.terrastories.app**](https://explore.terrastories.app/). {% endhint %} ### 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." {% hint style="info" %} If you don't see any Explore Terrastories settings, then you have to ask your Terrastories server administrator to set it up for you. Information about doing so (for server administrators) can be found in [Setting up an Explore Terrastories server](/setting-up-a-terrastories-server/setting-up-an-explore-terrastories-server), but in the case of the [**our.terrastories.app**](https://our.terrastories.app/) server, please get in touch with Digital Democracy. Information for doing so on the [Support](/miscellaneous/support) page. {% endhint %}
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:
{% hint style="info" %} In the future, we will make it possible for you to add your own map style for your Explore Terrastories view, and other settings too. {% endhint %} ### 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 [Setting up users and roles](/using-terrastories/using-the-terrastories-member-dashboard/setting-up-users-and-roles) and [Exploring and creating stories, speakers, and places](/using-terrastories/using-the-terrastories-member-dashboard/exploring-and-creating-stories-speakers-and-places). 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:
# Operating an offline Terrastories "Field Kit" {% hint style="info" %} These instructions are for operating an offline Terrastories "Field Kit" device once it has been set up for you. If you need to set one up, or pass along instructions to someone with an IT background that can help you, please refer to [🛖 Hosting Terrastories offline as a "Field Kit"](/setting-up-a-terrastories-server/hosting-environments/hosting-terrastories-offline-as-a-field-kit). \ \ There is also the option of [🍫 Hosting Terrastories on Kakawa (Earth Defenders Toolkit Offline)](/setting-up-a-terrastories-server/hosting-environments/hosting-terrastories-on-kakawa-earth-defenders-toolkit-offline) {% endhint %} Terrastories works on a mini-computer, which transmits a WiFi signal that other devices can use to open the application. We call this a :hut: 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! ## Steps to operate the Terrastories "Field Kit" #### **STEP 1.** Plug in the power cable and connect it to the Terrastories mini-computer.
#### **STEP 2.** Turn on the Terrastories mini-computer by pressing the “on/off” button. The button will light up, indicating that the mini-computer has started.
#### **STEP 3.** After about 30 seconds, you can connect to the Terrastories WiFi with your device.
#### **STEP 4.** Open your browser and go to terrastories.local. It will load the welcome screen. At this welcome screen, you can enter the site, or log in. You can also change the language of Terrastories.\ \ By logging in, you can add more stories or modify the content, or, set stories as restricted so they cannot be viewed without logging in.

NOTE: The URL should be terrastories.local instead of terrastories.io.

#### **STEP 5.** Interact with the Terrastories application :relaxed: You can either… Move around on the map to explore the lands, and press on points to filter the stories, or… You can use the sidebar to access stories and filter the places associated with them. On the mobile view, the sidebar is hidden by default. You can open it by pressing the top left arrow button.

NOTE: The URL should be terrastories.local instead of terrastories.io.

#### **STEP 6.** Turning off and storing the device. When you are done, turn off the Terrastories mini-computer by pressing the “on/off” button. Unplug the power cable.\ \ It is recommended that you keep the Terrastories mini-computer in the box for safekeeping and preventing dust from gathering.
# Preparing offline map packages {% hint style="warning" %} This page may require some technical knowledge about geospatial data. If the content of this page feels unfamiliar to you, get someone acquainted with geographic information systems (GIS) to help you. {% endhint %} {% hint style="info" %} If you have gone through all the below steps and your offline maps are *still* not showing up, you might be facing a commonly encountered issue described here: [Offline map tiles are not showing up](/miscellaneous/troubleshooting/offline-map-tiles-are-not-showing-up) {% endhint %} 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 [OpenMapTiles API](https://openmaptiles.org/). 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 [`mbtiles` ](https://docs.mapbox.com/help/glossary/mbtiles/#:~:text=MBTiles%20is%20a%20file%20format,from%20many%20different%20data%20sources.)or a [`pmtiles`](https://github.com/protomaps/PMTiles) 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 [Generating map files in .mbtiles format for the experimental Background Maps feature](https://docs.mapeo.app/complete-reference-guide/customization-options/custom-base-maps/creating-custom-maps/creating-mbtiles) in the Mapeo support materials has a visual, step-by-step guide for using QGIS to generate raster tiles. * **Generate tiles using mapgl-tile-renderer:** The [mapgl-tile-renderer ](http://github.com/conservationMetrics/mapgl-tile-renderer/)tool can be used to generate raster`MBTiles` from various sources including Bing Satellite, Esri World Imagery, Google Earth, and more, with an optional OpenStreetMap overlay. * **Convert tiles using tippecanoe:** There is also a command line tool called `tippecanoe` which can be used to generate vector `MBTiles` or `PMTiles` from Esri Shapefiles and other formats: [guide](https://docs.mapbox.com/help/troubleshooting/large-data-tippecanoe/). * **Convert tiles using mbutil:** If you already have tiles in a different format (such as `xyz`), you can use a Node command line tool called `mbutil` to convert them to `MBTiles`. Please see our [xyz to mbtiles conversion repository](https://github.com/digidem/xyz-mbtiles-conversion) or this page [Generating map files in .mbtiles format for the experimental Background Maps feature](https://docs.mapeo.app/complete-reference-guide/customization-options/custom-base-maps/creating-custom-maps/creating-mbtiles) in the Mapeo support materials for more information. 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 [guide](https://docs.mapbox.com/mapbox-gl-js/style-spec/) 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 [Mapbox Studio](http://mapbox.com/studio) 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 [here](https://docs.mapbox.com/studio-manual/guides/). * 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`. * Next, you will need to make some changes. The `style.json` from Mapbox will be referring to an online URL for the map sources. You need to change this to refer to the local `MBTiles`. Change `sources` > `composite` > `url` to the following format: `"url": "mbtiles://mbtiles/name.mbtiles"`. (Here, `name` is just an example; it can be called whatever you want, so long as the filename is the same.) 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. {% hint style="info" %} Note: it is also possible to use [Maputnik](https://maputnik.github.io/), the open-source visual editor for the Mapbox style specification, to style your `MBTiles`data. {% endhint %} ### **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`: ``` { "version": 8, "name": "Terrastories offline raster map", "sources": { "terrastories-raster-mbtiles": { "type": "raster", "url": "mbtiles://tiles.mbtiles" // or pmtiles } }, "layers": [ { "id": "background", "type": "background", "paint": {"background-color": "hsl(47, 26%, 88%)"} }, { "id": "terrastories-raster-mbtiles", "type": "raster", "source": "terrastories-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. # Hosting environments {% hint style="warning" %} These pages may require some technical knowledge about server hosting and deployment. If the content of this page feels unfamiliar to you, get someone acquainted with information technology (IT) to help you. {% endhint %} 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: * [🌐 Hosting Terrastories online](/setting-up-a-terrastories-server/hosting-environments/hosting-terrastories-online)**:** 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.
* [🛖 Hosting Terrastories offline as a "Field Kit"](/setting-up-a-terrastories-server/hosting-environments/hosting-terrastories-offline-as-a-field-kit): 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.
* :chocolate\_bar: **Hosting Terrastories on Kakawa (Earth Defenders Toolkit Offline)**: Terrastories also comes bundled on [*Kawaka*](https://www.earthdefenderstoolkit.com/deploy/). Please see the documentation for using Kakawa [here](https://docs.earthdefenderstoolkit.com/overview/introduction).
# 🌐 Hosting Terrastories online {% hint style="warning" %} This page may require some technical knowledge about server hosting and deployment. If the content of this page feels unfamiliar to you, get someone acquainted with information technology (IT) to help you. {% endhint %} *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 [storage.yml](https://github.com/Terrastories/terrastories/blob/master/rails/config/storage.yml) 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 [https://mapbox.com](https://mapbox.com/) 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 [https://aws.amazon.com](https://aws.amazon.com/), 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 [Getting Started](https://aws.amazon.com/s3/getting-started/) 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 [prices ](https://aws.amazon.com/s3/pricing/)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 [https://heroku.com](https://heroku.com/) 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: | Key | Value | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | ACTIVE\_STORAGE\_SRC | production | | AWS\_ACCESS\_KEY | *Add your AWS user access key here.* | | AWS\_BUCKET\_NAME | *Add your AWS bucket name here.* | | AWS\_SECRET\_ACCESS\_KEY | *Add your AWS bucket name here.* | | AWS\_REGION | *Add the region for your AWS bucket name here.* | | DATABASE\_URL | *This will be provided by setting up the Heroku Postgres add-on.* | | LANG | en\_US.UTF-8 | | MAPBOX\_ACCESS\_TOKEN | *Add your Mapbox access token here* | | MAPBOX\_STYLE | *Add your default Mapbox style here.* | | PROJECT\_PATH | rails | | RACK\_ENV | production | | RAILS\_ENV | production | | RAILS\_LOG\_TO\_STDOUT | enabled | | RAILS\_MASTER\_KEY | 7a0c538b904d5919af7c11470f3b7a4b | | RAILS\_SERVE\_STATIC\_FILES | enabled | | SECRET\_KEY\_BASE | 53316f279e788bae0a2d4f65ec3e213368e216a9ce18757e5305eb854dee98be34dc1f160b6a165832797be1f699a66d4109fd7f719888cbf920e6196fb18500 | 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 [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) 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.
# 🛖 Hosting Terrastories offline as a "Field Kit" {% hint style="warning" %} This page may require some technical knowledge about server hosting and deployment. If the content of this page feels unfamiliar to you, get someone acquainted with information technology (IT) to help you. {% endhint %} *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"](/operating-terrastories-offline/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 [documentation for developers on Github](https://github.com/Terrastories/terrastories). {% hint style="info" %} It is possible to install Terrastories on Windows or Mac OS; however, this workflow has only been fully tested on a Linux OS. You may need to take different steps for some of the setup depending on the operating system; for example, the `hosts` and Hotspot network manager files may reside in a different location. {% endhint %} ## 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 {% hint style="success" %} Quick Install sets up a new database and utilizes Terrastories default map style. If you wish to use your own map style, please see [advanced setup](/setting-up-a-terrastories-server/hosting-environments/hosting-terrastories-offline-as-a-field-kit/advanced-setup) for more information. {% endhint %} To quick install Terrastories for offline usage, run the following command in the terminal: ``` /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Terrastories/offline-field-kit/main/install.sh)" ``` 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 [our Github repository](https://github.com/terrastories/offline-field-kit) 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 [Advanced Setup](/setting-up-a-terrastories-server/hosting-environments/hosting-terrastories-offline-as-a-field-kit/advanced-setup). 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): ``` docker compose up ``` {% hint style="info" %} At this point, you may bring your "field kit" offline. {% endhint %} ## 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 [Operating an offline Terrastories "Field Kit"](/operating-terrastories-offline/operating-an-offline-terrastories-field-kit).
Next, you can make your Hotspot autoconnect on reboot by entering the following command in the terminal: ``` nmcli con mod connection.autoconnect yes ``` {% hint style="info" %} Make sure none of your WiFi connections are enabled to connect automatically. {% endhint %} #### 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: ``` sudo apt-get install ubuntu-restricted-extras ``` #### Bypass login screen on boot For the [Operating an offline Terrastories "Field Kit"](/operating-terrastories-offline/operating-an-offline-terrastories-field-kit) 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 [guide for bypassing login screen on boot](https://askubuntu.com/questions/256239/how-to-bypass-login-screen-on-boot). #### Set operating system to shutdown upon pressing power button Similarly, for the [Operating an offline Terrastories "Field Kit"](/operating-terrastories-offline/operating-an-offline-terrastories-field-kit), 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: ``` event=button/power action=/sbin/poweroff ``` Save and close the file, and run: ``` sudo service acpid restart ``` #### Set operating system to start Docker on boot Here is a [guide for configuring Docker to start on boot](https://docs.docker.com/install/linux/linux-postinstall/#configure-docker-to-start-on-boot), if needed. #### Set Docker to operate without sudo access Here is a [guide for configuring Docker to operate without sudo](https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user), if needed. ## Bringing Terrastories offline You are now ready to bring Terrastories to an offline context! From here, you can run the command: ``` docker compose up ``` 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 [Operating an offline Terrastories "Field Kit"](/operating-terrastories-offline/operating-an-offline-terrastories-field-kit), which does not require any technical knowledge. # Advanced Setup ## Use a custom offline map package {% hint style="info" %} If you already have a custom map style package, you can proceed. Skip this configuration if you are comfortable using the default maps. Or, [prepare your own map package](/operating-terrastories-offline/preparing-offline-map-packages) for offline use and come back. {% endhint %} Add your map package to the `map/data` folder. You can [prepare your own](/operating-terrastories-offline/preparing-offline-map-packages) or download our default map package [here](https://github.com/Terrastories/default-offline-map/). Your `map/data` folder structure should look like: ``` data/ ├── fonts/ │ └── Font Name/ │ ├── font.pbf │ └── ... ├── sprites/ │ ├── sprite.png │ └── ... ├── tiles.pmtiles ├── style.json └── config.json ``` {% hint style="info" %} The three files that are absolutely required are `style.json`, `config.json`, and one or more tile sources (in `mbtiles` or `pmtiles` format). Fonts and sprites are only needed if your style is using them. {% endhint %} Your style specification must include reference to the name of your style: ```json { "sources": { "terrastories-map": { // This MUST be terrastories-map OR you MUST update the config.json file to reflect your chosen name "type": "vector", // or raster "url": "pmtiles://tiles.pmtiles" // or "mbtiles://tiles.mbtiles". If your tile filename has a different name instead of "tiles", then change that too. } }, "sprite": "sprite", // optional, only needed if your style utilizes sprites by name "glyphs": "{fontstack}/{range}.pbf", // optional, only needed if your style utilizes fonts by name // the rest of your style specifications } ``` For more information on custom maps, please see the Github repository [README.md](https://github.com/Terrastories/offline-field-kit/blob/main/map/README.md). ## 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: ```diff web: image: terrastories/terrastories:latest restart: unless-stopped depends_on: - db ports: - 80:3000 - 3000:3000 environment: - RAILS_ENV=offline - HOST_HOSTNAME=terrastories.local - - TILESERVER_URL=http://terrastories.local:8080/styles/terrastories-map/style.json + - TILESERVER_URL=http://localhost:8080/styles/terrastories-map/style.json - DATABASE_URL=postgresql://terrastories:terrastories@db:5432/terrastories volumes: - ./media:/media - ./import:/api/import/media - tileserver: - restart: unless-stopped - image: terrastories/terrastories-map:latest - ports: - - 8080:8080 ``` ## Set up a custom Hostname In order to access your Terrastories instance, you'll need to configure a domain. {% hint style="danger" %} Access via "localhost" is disabled for offline mode for security. You must set a custom hostname for domain access. {% endhint %} 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: ``` 127.0.0.1 terrastories.local ``` Save and close. {% hint style="info" %} Replace `terrastories.local` with your desired host name. {% endhint %} If you utilized a custom domain (not terrastories.local), update your `compose.yaml` file: ```diff web: image: terrastories/terrastories:latest restart: unless-stopped depends_on: - db ports: - 80:3000 - 3000:3000 environment: - RAILS_ENV=offline - - HOST_HOSTNAME=terrastories.local + - HOST_HOSTNAME=your-custom-domain.local - - TILESERVER_URL=http://terrastories.local:8080/styles/terrastories-map/style.json + - TILESERVER_URL=http://your-custom-domain.local:8080/styles/terrastories-map/style.json - DATABASE_URL=postgresql://terrastories:terrastories@db:5432/terrastories volumes: - ./media:/media - ./import:/api/import/media ``` # 🍫 Hosting Terrastories on Kakawa (Earth Defenders Toolkit Offline) Terrastories also comes bundled on [*Kawaka*](https://www.earthdefenderstoolkit.com/deploy/). Please see the documentation for using Kakawa [here](https://docs.earthdefenderstoolkit.com/overview/introduction). # Navigating the Super Admin dashboard 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 ). 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.
{% hint style="info" %} The super admin can only see a total of stories, places, speakers, and users. They are *not* able to view any individual data associated with a community. This is an important point that relates to **data sovereignty** - on a Terrastories server, even the server's super admin is not able to access any community data without permission. {% endhint %} ### 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`, `sw`, `pu`...). In the future, we may use this to set a default language for a community when logged in. * **Username** (required): This will be an admin user of the community, used to log in to the community and to create other users, and set theme and map settings. * **Password** (required): The password for the admin user for the community. * **Email**: Email address associated with the admin user. This can be used to send emails by the Terrastories in the future, for example, for the purposes of resetting a password.
{% hint style="warning" %} In addition to editing, or creating communities, the super admin can also **delete** a community. Doing so may be desirable if there is a community that was e.g. created for demo purposes and is taking up unnecessary storage space. Doing so is NOT reversible so it is advisable to carefully consider whether this is the right decision. {% endhint %} ### 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.

Feature Flags showing public_communities enabled, which adds the Explore Terrastories opt-in functionality for communities.

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 [EXPLORE TERRASTORIES](/explore-terrastories/what-is-explore-terrastories). 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:

public_communities enabled for the Terrastories demo community, which means they will now see the Explore Terrastories opt-in functionality on their Settings page.

### 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. {% hint style="danger" %} It is highly recommended to change the password of the super-admin username once you set up a new Terrastories server. {% endhint %} # Setting up an Explore Terrastories server {% hint style="warning" %} These pages may require some technical knowledge about server hosting and deployment. If the content of this page feels unfamiliar to you, get someone acquainted with information technology (IT) to help you. {% endhint %} The [EXPLORE TERRASTORIES](/explore-terrastories/what-is-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](/using-terrastories/using-the-terrastories-member-dashboard/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 [the Github repository](https://github.com/terrastories/explore-terrastories) for more information. Explore Terrastories is a [Create React App](https://create-react-app.dev/) 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 [instructions](https://create-react-app.dev/docs/deployment) 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[Navigating the Super Admin dashboard](/setting-up-a-terrastories-server/navigating-the-super-admin-dashboard#features-working-with-feature-flags). # Support ### Technical support For help with common technical issues, see the [Troubleshooting](/miscellaneous/troubleshooting) 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 [Ruby for Good Slack](https://rubyforgood.slack.com/join/shared_invite/zt-1kfeimohe-KL~~~6Lkof7G94_7Ojd_Hw#/shared-invite/email). If you're a developer or comfortable using GitHub, you can file an issue in the corresponding repository [here](https://github.com/terrastories/terrastories). ### Online server access Digital Democracy maintains an online Terrastories server at . If you would like to request a community account on our server, please [write to us](mailto:info@digital-democracy.org). ### Support starting a Terrastories project In addition to all of the resources compiled in this guide, there is a community of active users and maintainers of Terrastories that participate in Digital Democracy's public chat channel on [Discord](https://discord.gg/KWRFDh3v73) and on our [Earth Defenders Toolkit Forum](https://forum.earthdefenderstoolkit.com/). We encourage you to consult these spaces for additional tips and ideas on how people are using Terrastories. Digital Democracy's core team is very small and we have limited capacity to provide direct accompaniment for implementing Terrastories outside of our existing partnerships. In some cases we are able to offer support. To read more about the way we work with partners and different levels of support, see [here](https://drive.google.com/file/d/1c9C1-6v1EHKnfrYDsBn3VNu5qS_pUNMC/view?usp=sharing). # Troubleshooting See additional information and troubleshooting steps for some common technical issues in the pages below: * [Offline map tiles are not showing up](/miscellaneous/troubleshooting/offline-map-tiles-are-not-showing-up) * [Saving and printing Terrastories reference materials](/miscellaneous/troubleshooting/saving-and-printing-terrastories-reference-materials) * [Resetting passwords (using the Rails console)](/miscellaneous/troubleshooting/resetting-passwords-using-the-rails-console) # Offline map tiles are not showing up 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 [Preparing offline map packages](/operating-terrastories-offline/preparing-offline-map-packages) for more. 2. **Your map tiles cover a small area, and you are not sufficiently centered, and zoomed in, on that area.** Many map tilesets start at zoom level 0, which is the whole world; hence, when you zoom out on Terrastories, you should start to see some tiles, and as you zoom in, you can see where the area that your tileset covers is located. However, some map tilesets may start at a much higher zoom level and are therefore hard to find on the map. To resolve this, we recommend setting a Zoom Level and Center coordinates, along with Map Bounds to avoid the user from traveling far away from your tiles. (You might need to get the coordinates for these from the source who created the map tiles, or use a tool like [Mapbox Location Helper](https://demos.mapbox.com/location-helper/) to figure them out.) See [Modifying map settings](/using-terrastories/using-the-terrastories-member-dashboard/modifying-map-settings) for more. {% hint style="info" %} Still having issues? Access the console in your browser's developer tools to see if there are any errors. If you need help interpreting these, please see [Support](/miscellaneous/support) for ways to get help. {% endhint %} # Resetting passwords (using the Rails console) {% hint style="warning" %} This page requires some technical knowledge about server administration, and also requires you to have direct access to the server where your Terrastories server is hosted. \ \ If the content of this page feels unfamiliar to you, get someone acquainted with server administration to help you. {% endhint %} 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 [Rails console](https://guides.rubyonrails.org/command_line.html), however. Depending on your hosting environment, the way you access the Rails console may differ: * On a "Field Kit" or Kakawa Terrastories server, you will need to first get into the `terrastories-web` Docker container's shell, like this: ``` $ docker compose exec web /bin/bash ``` * For online hosting services like Heroku, you can either use a web console or access the server via ssh. Once you are logged into the Docker container, you can access the rails console from the Terrastories directory: ``` bin/rails console ``` Now, you can update the password for the user (in case of the Terrastories super-user, the username is `terrastories-super`): ``` u = User.find_by(email: email) u.update!(password: "newpassword", password_confirmation: "newpassword") ``` # Saving and printing Terrastories reference materials 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 ![](/files/azjsZ9N6bwQrgMiBErt9)**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: * **Only this page**\ Export only the content of the current page * **This page and it's subpages**\ Export this page and all of its subpages (only available for pages with subpages) * **Entire space**\ Export all pages from the Terrastories Materials guide
Click on **Export.** Once your file is ready to be downloaded, click on **Download** to save the file.
{% hint style="info" %} Please note that when exporting multiple pages, the export preparation may take several minutes. {% endhint %} The resulting PDF file will be saved in your **Downloads** folder by default. ### Print a PDF Once you have exported a PDF of the desired material, locate the saved PDF file on your device and double click it to open. Go to **File** and select **Print**. # Translating Terrastories 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](https://github.com/terrastories/terrastories), and follow these steps. 1. Find the two or three-digit ISO language code for your language contribution [here](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) 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 🎉

At the time this screenshot was taken, we have the following languages available (in alphabetical order): Amharic, English, Spanish, Hindi, Japanese, Matawai, Dutch, Portuguese, Punjabi, Swahili, and Chinese (Mandarin).

# Additional resources and references Some other guides, references and manuals about mapping and storytelling that could be of use as you design your project. ## About Terrastories ### Overview * :arrow\_forward: [What is the Earth Defenders Toolkit?](https://www.youtube.com/watch?v=i2VHSX6rLCg) | **Digital Democracy 2023** (documentary about an earth defenders retreat in Ecuador with testimonies about Terrastories) \[EN] * :arrow\_forward: [Mapping your place-based oral histories with Terrastories](https://www.youtube.com/watch?v=cybEjHDFKAA) | **Indigenous Mapping Workshop 2021** (46-min video of a practical workshop) \[EN] * :arrow\_forward: [Terrastories Demo](https://www.youtube.com/watch?v=jiWVxZefNGk) | **Indigenous Mapping Workshop 2020** (16 min-video) \[EN] * :arrow\_forward: [Lightning Talk: Terrastories](https://youtu.be/ThAHqHxmEPk) | **MozFest 2022** (7-min video) \[EN] * :arrow\_forward: [Open-source tech built with local & marginalized communities for mapping, safeguarding, and protecting oral histories](https://www.youtube.com/watch?v=KQIzByWP8QQ\&feature=emb_title) | **Code4Lib 2021** keynote (40-min video) \[EN] * :book: Terrastories | [*Evaluating Participatory Mapping Software*](https://terrastories.app/wp-content/uploads/2023/10/Burnett-2023-Evaluating-Participatory-Mapping-Software.pdf) published by Springer, 2023 \[EN] ### Examples of Terrastories projects * :earth\_africa: [Explore Terrastories](https://explore.terrastories.app/) | Explore multiple communities worldwide that have opted to share some of their content with a greater public * :book: [Matawai: Place-based storytelling in Suriname](https://www.earthdefenderstoolkit.com/community/matawai-place-based-storytelling-in-suriname/) (case study) \[EN / ES / PT / FR / KM / SW / TH / VI] * :book: [Ohneganos: Indigenous mapping](https://www.ohneganos.com/indigenous-mapping) \[EN] ## Other resources * :books: [Earth Defenders Toolkit](https://www.earthdefenderstoolkit.com) (a website that includes multiple guides, videos, case studies, etc.) \[EN / ES / PT / FR] * :book: [Mapping and recording place-based oral histories: a methodology](https://terrastories.app/wp-content/uploads/2023/07/ACT_OralHistories_Guide_2019_ENGLISH.pdf) | The Amazon Conservation Team (guide, PDF) \[EN / NL] * :book: [Terrastories Community Mapping Project at Six Nations: A Ratikararò:roks (Story Gatherers) Training Guide for the Stewardship of Haudenosaunee Ecological Knowledge](https://terrastories.app/wp-content/uploads/2023/10/Six-Nations-Terrastories-1.pdf) | Ohneganos Ohnegahdę:gyo (guide, PDF) \[EN] * 📝 [ODK / KoboToolbox form to collect places and stories for Terrastories in the field](https://terrastories.app/now-available-an-odk-kobotoolbox-form-to-collect-places-and-stories-for-terrastories-in-the-field/) # For developers Are you interested in helping build Terrastories? We :heart: 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 [open issues](https://github.com/terrastories/terrastories/issues) are indexed by priority and difficulty. All of our developer onboarding documentation is on our Github.
Please see our [Wiki](https://github.com/terrastories/terrastories/wikihttps://github.com/terrastories/terrastories/wiki), and read our [How to Contribute](https://github.com/Terrastories/terrastories#contributing) guide for more information on Terrastories development. **Roadmap:** to learn about current open source development work or where we're headed, check out our [Vision Statement](https://github.com/Terrastories/terrastories/wiki/Vision-Statement) and our [Roadmap](https://rudokemper.notion.site/rudokemper/9b66a992e88c453da974d583651e098d?v=058ca47b36774a8983dbd9e36d37396c). **Community:** join us [on Github](https://github.com/terrastories/terrastories) or in the [Ruby for Good Slack](https://rubyforgood.slack.com/join/shared_invite/zt-1kfeimohe-KL~~~6Lkof7G94_7Ojd_Hw#/shared-invite/email) #terrastories channel. **Coding events**: In the past, Terrastories has been built at [Ruby for Good 2018](https://www.amazonteam.org/act-partakes-in-ruby-for-good-2018-to-develop-offline-geostorytelling-app-terrastories-for-remote-communities/), [Ruby by the Bay 2019](http://rubybythebay.org/), [Ruby by the Bay 2020](http://rubybythebay.org/), and [during Hacktoberfest](https://medium.com/@rudokemper/a-very-happy-hacktoberfest-for-terrastories-and-the-ruby-community-9e472d9e85d3). If you are interested in having Terrastories at a coding event, please [get in touch with us.](https://terrastories.app/contact-us)

Terrastories architecture as of 2022