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

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

Terrastories 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). 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.

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.

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.

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 Basic information about Terrastories, FAQs, how to get started, and our demo.

• USING TERRASTORIES 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 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 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 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.

Feel free to make use of these resources under the creative commons license terms: Attribution-NonCommercial 4.0 International.

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

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.

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.

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.

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.

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

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 and briefly let us know how you plan to use the online server. We'd be happy to create an account for you.

• Who made Terrastories?

• Is Terrastories free to use?

• Where can I check out Terrastories in action?

• How do you install Terrastories?

• What is the difference between Terrastories and story maps?

• Is Terrastories a data collection tool?

• What kind of data does Terrastories work with?

• What languages is Terrastories available in?

• How does Terrastories work offline?

• Who will have access to my data?

• Can you help me deploy 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 when working with the Matawai, an Afro-descendant Maroon community in Suriname, and was first built by Ruby for Good, 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.

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

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).

Digital Democracy also maintains an online Terrastories server at https://our.terrastories.app. If you would like to request a community account on our server, please write to us.

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 (or any other mapping tool on the Earth Defenders Toolkit 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 workflow in Kakawa (the offline Earth Defenders Toolkit build)

There is also an ODK / KoboToolbox survey form 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.

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.

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.

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.

Lastly, the super admin of a Terrastories server does not have access to your data. Through the 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 and on our Earth Defenders Toolkit Forum. 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.

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.

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.

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.

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

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

• Import: a dashboard for importing data in CSV format. See 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:

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.

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

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

The Explore Terrastories interface offers a much streamlined and improved over what is offered in 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:

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.

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

Once you are done, click Import. The data will now be added to Terrastories.

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.

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 first thing that you will be greeted with upon accessing Terrastories is the welcome page.

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

For an online Terrastories server:

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

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

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

For an offline Terrastories server:

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

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

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

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

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

The Terrastories main interface

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

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

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

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

• 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.

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.

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

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

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 file)

1. Fork the Terrastories repository on Github

On Github, fork the Terrastories repository master branch at https://github.com/terrastories/terrastories 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 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, 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 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 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 and sign up for an account. As of December 2022, this needs to be a Hobby account ($7/month), or higher to improve your server’s performance and security (SSL).

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

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

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

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

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

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

• heroku/ruby

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

Lastly, as of March 2022, currently Heroku apps with a heroku-20 stack are not deploying Terrastories due to our Ruby dependency being out of date. For the time being, you need to downgrade the Heroku stack to heroku-18 by installing the 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.

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. 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 or a 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 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 tool can be used to generate rasterMBTiles 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.

• 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 or this page Generating map files in .mbtiles format for the experimental Background Maps feature 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 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 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.

• 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.

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.

Please see EXPLORE TERRASTORIES for this.

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

Use a custom offline map package

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

data/
├── fonts/
│   └── Font Name/
│       ├── font.pbf
│       └── ...
├── sprites/
│   ├── sprite.png
│   └── ...
├── tiles.pmtiles
├── style.json
└── config.json

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

{
  "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.

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:

  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.

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.

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

  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

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.

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, 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.

• 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.

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.

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.

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.

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: 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 https://our.terrastories.app server) and hope to have instructions for other services soon.

• 🛖 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.

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

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

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

Prerequisites

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

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

Install Terrastories

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

/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 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.

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

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".

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

nmcli con mod <Hotspot-network-name> connection.autoconnect yes

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" 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.

Set operating system to shutdown upon pressing power button

Similarly, for the 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, if needed.

Set Docker to operate without sudo access

Here is a guide for configuring Docker to operate without sudo, 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", which does not require any technical knowledge.

Exploring, adding and editing stories

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

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

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

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

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

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

Exploring, adding and editing speakers

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

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

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

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

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

Exploring, adding and editing places

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

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

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

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

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

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

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

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

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.

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:

• 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:

Now, you can update the password for the user (in case of the Terrastories super-user, the username is terrastories-super):

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:

Technical support

Online server access

Support starting a Terrastories project

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

Super admin dashboard

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

Metrics

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

Managing and creating communities

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

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

Creating a new community

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

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

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

• Locale: the language used by the community, by language ISO code (e.g. en, es, pt, 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.

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.

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

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

Default super admin on a new Terrastories server

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

Deployment

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.

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 are indexed by priority and difficulty.

All of our developer onboarding documentation is on our Github.

Please see our Wiki, and read our How to Contribute 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 and our Roadmap.

Community: join us on Github or in the Ruby for Good Slack #terrastories channel.

Coding events: In the past, Terrastories has been built at Ruby for Good 2018, Ruby by the Bay 2019, Ruby by the Bay 2020, and during Hacktoberfest. If you are interested in having Terrastories at a coding event, please get in touch with us.

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

Translation using Github

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

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

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

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 🎉

About Terrastories

Overview

Examples of Terrastories projects

Other resources

• 📝 ODK / KoboToolbox form to collect places and stories for Terrastories in the field

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

Save a PDF

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

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

• 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.

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.

Opting in to use, and configuring Explore Terrastories

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

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

There are a few options here:

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

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

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

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

Selecting Stories to be show on Explore Terrastories

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

Before you activate "Enable public interface", make sure you are sharing only the stories that you want to share by going through your Stories list, and ensuring that anything that should not be shown to the public is NOT set to an anonymous permission level. For more information on this, please see Setting up users and roles and 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: