Skip to content

Terrastories is a geostorytelling application built to enable local communities to locate and map their own oral storytelling traditions about places of significant meaning or value to them. Check out our Wiki for open source development information.



Switch branches/tags

Latest commit

* Add nginx proxy to Docker Compose

This is the first step to a better, more uniform set up. Documentation and setup instructions will come later.

Using localhost:3000 will continue to work as expected.

If you wish to trail this out, add the following to your /etc/hosts: terrastories.local

* Docker Compose adjustments

* Add Geocoder to help render static maps

* Disable evented file watcher && don't replace images on attach on many

* Save cookie session at root to be shared across multiple subdomains

* Add custom devise failure app to customize redirect on failure url

* New CMS/member layout show and index views

* Refactor Stories index to infinite scroll

* Refactor Infinite Scroll to be universal

Add infinite scroll to:
- Users
- Speakers
- Places

* Add overlay to image control hover and add en translations for hardcoded strings

* Ability to add new users

Also adds new style for basic button links (will need to extend)

* Add create/update actions and views to Places

* Add Stories create/update

* Use shared form error partial

* Add Speakers create/update

* Add destroy action to place, speaker, story, and user

* Restrict access to edit/delete links using policies

Also ensure hardcoded text is properly internationalized

* Customize nginx 502 and 503 error pages

This page will autorefresh every 2 seconds while the backend server

* Streamline docker-compose file

* Fix unrestricted bounds checkbox

* Include 504 in custom loading page

* Update for offline maps

* Properly redirect back to app link

* Use ENV[] to not error on load

* Add dropdown for profile / logout

* Fix Stories filters

* Fix next page meta for paging

* [Feature] Add search

* Adjust some styling for filters and sidebar

* Fix default mapbox config

* Style tweaks and cleanup on Theme

* Theme updates

- fixes issue with unrestricted bounds / being checked if one boundary
  is empty but others are set (e.g. should not be checked)
- fixes redirect/render issue (no errors) if theme form fails

* Fix: unchecking unrestricted bounds

* Ensure Dashboard views are ready for translation

Not all keys are translated yet. I did my best to copy them over from
existing translations, but there are English translations in certain
places due to not having a one-to-one existing translation.

Note: Some translations are duplicated between Administrate and
Dashboard; if you are ADDING: please add to DASHBOARD. This is what will
be used long term; the administrate ones will be removed when
administrate is removed.

Model validations were updated and translated as well, which is not
something that was the case before.

* Use generic 'P' if name is not set; we may need to add additional validations

* Use set_locale in default locale so forms are correctly translated / redirected with translation

* Adjust more styles

* Remove use of subdomains

* Restructure for latest compose && offline/dev profiles

* Remove unnecessary initializer

* Swap out mini_magick gem for new image_processing gem

* Fix: Docker config and .env.example for default env

* Remove unused vhost in nginx proxy

* Update image hover controls to be more generic for any media

* Ensure video_unsupported is available in general translations

* Move remote deletion for active storage attachments to be available throughout all of dashboard

* Story media can be viewed and deleted from form

* Speaker photo can be deleted from form

* Allow replacement of image on remote deletion

* Replace Speaker photo with default on removal

* Place photo can be deleted from form

* Improve audio player and don't show on edit

* Add in-form filelist for non-image file lists

* Place name_audio can be deleted from edit

* User photo can be deleted from form

* Display labels as blocks

* Theme background image can be deleted from edit

* Readd in show_resource translation for search

* Super Admin - Communities (basic)

* Fix: Permissions and policy scopes for viewer and member roles

* Fix: role permissions on speakers controller

* Fix: infinite scroll on places and speakers

* Fix community infinite scroll for super admins

* Redirect super admin to new dashboard instead of administrate

* Add metrics to super admin

* Add filters to communities (name search)

* Fix: `meta_param` -> `meta_params`

* Add less to Dockerfile for console use

* Remove unused photo db attribute on speaker

* Fix: showing non-previewable videos

* Fix: card truncate for long descriptions and overflow on links

* Fix: don't display badge if content empty

* Fix: missing translation for speaker community

* Fix: story filter labels

* Adapt wording for sponsor logos in Themes edit view

* Feat: Move import from Administrate to new CMS

This creates one singular place to import records.

* Add missing translation for Import

* Fix: video not rendering on story edit

* Fix: changes to bbox input are updated on map movement

* Remove back to app link for super admins

* Fix: incorrect conditional on places list for showing type of place badge

* Make description a textarea and after name

* Change Name Audio to Placename Audio in translations

* Update Story place section to use badges to display type of place and region

* Reorg colors

* Update badges to have different colors based on logo

* Fix: line-height mismatch on narrow cards

* Move name audio player to display next to name, not on new line

* Give forms a slight style overhaul

* Add ability to mark field as required in forms

* Fix: form styles for filters and search bar

* Theme: lat/lng on bounding box is restricted to 5 decimal places.

* Add python2 to the Dockerfile

* Remove scroll on columns

* Fix: video not showing on stories edit

* Add word wrap option to card with new class; wrap emails on user list

* update docs with new docker scripts and CMS info

* Update Windows docs

* Fix: header mismatch logic should be reversed

* Remove unused file from spiking out logic

* Display Flash messages correctly

Co-authored-by: Rudo Kemper <>

Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Table of Contents

  1. About Terrastories

  2. Install Terrastories

  3. Setting up Communities and Users

  4. Customize Terrastories

  5. Demo and Tutorials

  6. Developing with Terrastories

  7. Contributing Guidelines

About Terrastories

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. It is a dockerized Rails app that uses Mapbox to help users locate content geographically on an interactive map. Terrastories is designed to be entirely offline-compatible, so that remote communities can access the application entirely without needing internet connectivity.

The Terrastories interface is principally composed of an interactive map and a sidebar with media content. Users can explore the map and click on activated points to see the stories associated with those points. Alternatively, users can interact with the sidebar and click on stories to see where in the landscape these narratives took place. Through an administrative back end, users can also add, edit, and remove stories, or set them as restricted so that they are viewable only with a special login. Users can design and customize the content of the interactive map entirely, and the interface itself is customizable with a color scheme and design reflecting the style of the community.

Learn more about Terrastories at

Terrastories: Matawai Konde 1.0 (October 2018)

Install Terrastories

Before you install Terrastories, you should consider the hosting environment for the application. Will it be hosted on an online server? If so, you are likely going to need to set up Terrastories on a Linux server. Are you installing Terrastories on your local machine, either for development or for demoing the app? Depending on what operating system you use, there are different setup guides, below. Lastly, if you are installing Terrastories to work fully offline (i.e. no online maps), there is a special guide for that use case as well.

To install and run a streamlined version of Terrastories with access to an online map on, visit one of these links:

  1. Setup for Mac
  2. Setup for Windows
  3. Setup for Linux

To install and run Terrastories for offline "Field Kit" usage, visit:

  1. Setup for offline

Setting up Communities and Users

Terrastories is built to host multiple communities with their own maps and stories on one Terrastories application. The communities' data is protected and accessible only through their own user credentials, with different layers of permissions like viewing, editing, and changing settings for the whole community.

Terrastories is set up in this way to enable multiple communities to leverage one hosting environment (online or offline) instead of having to set up a dedicated server, while retaining sovereignty over their data. In the future we will make it possible to enable selective sharing between communities across Terrastories, when desired.

To learn how to set up Terrastories community instances and users, see our community setup guide.

Customize Terrastories

To set up Terrastories with a custom map, languages, visual assets, and to import data, see our customization guide.

Demo and Tutorials

In anticipation of the Terrastories technical session taking place at the 2020 Indigenous Mapping Workshop, we prepared three self-guided tutorials along with video walkthroughs per tutorial. We also put together a comprehensive video showing the application's core features, and a live demo to explore.

These can be found on the Terrastories website.

Developing with Terrastories

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

For a general overview of the application as well as a Vision statement and Roadmap, please see our Wiki.


We contributors! By participating in this project, you agree to abide by the Ruby for Good Code of Conduct.

First: if you're unsure or afraid of anything, just ask or submit the issue or pull request anyways. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that.

How To Contribute To Terrastories

Step 1: Learn a little about the app One of our core contributors @mirandawang wrote a really nice outline of the app. Unless you are working on something related to Docker containers or to map cartography then you will benefit from taking a couple minutes to get acquainted with the app. You can also check out our roadmap to see where things are going with Terrastories development.

Step 2: Find an issue to work on Please find an issue that you would like to take on and comment to assign yourself if no one else has done so already. All issues with the label status: help wanted are up for grabs! We will add the status: claimed label to the issue to mark it as assigned to you. Also, feel free to ask questions in the issues, and we will get back to you ASAP!

Step 3: Fork the repo Click the "fork" button in the upper right of the Github repo page. A fork is a copy of the repository that allows you to freely explore & experiment without changing the original project. You can learn more about forking a repo in this article.

Step 4: Create a branch Checkout a new branch for your issue - this branch can be named anything, but we encourage the format XXX-brief-description-of-feature where XXX is the issue number.

Step 5: Happy Hacking! Follow the instructions in the Setup Document to set up your local environment. Feel free to discuss any questions on the issues as needed, and we will get back to you! Don't forget to write some tests to verify your code. Commit your changes locally, using descriptive messages and please be sure to note the parts of the app that are affected by this commit.

Step 6: Pushing your branch and creating a pull request Push your branch up and create a pull request! Please indicate which issue your PR addresses in the title.

Code Reviews & Pull Request Merging

Once you've submitted a pull request, a core contributor will work with you on doing a code review (typically pretty minor unless it's a very significant PR). If the reviewer gives a to the PR merging, then huzzah! Merge into master! If your feature branch was in this main repository (and not forked), please delete your branch after it has been merged.

Stay Scoped

Try to keep your PRs limited to one particular issue and don't make changes that are out of scope for that issue. If you notice something that needs attention but is out-of-scope, put a TODO, FIXME, or NOTE comment above it.

Work In Progress Pull Requests

Sometimes we want to get a PR up there and going so that other people can review it or provide feedback, but maybe it's incomplete. This is OK, but if you do it, please tag your PR with an in-progress label so that we know not to review / merge it.

Becoming a Core Steward

Users that are frequent contributors and are involved in discussion may be given direct Contributor access to the Repo so they can submit Pull Requests directly, instead of Forking first. You can join us in Slack here, and find us in the channel #terrastories! :)