Readme changes to reflect multi-instance architecture and other recen…

…t changes

README.md

@@ -4,15 +4,17 @@
 
 1. [About Terrastories](#about-terrastories)
 
-2. [Setup Terrastories](#setup)
+2. [Install Terrastories](#install-terrastories)
 
-3. [Customize Terrastories](#customize-terrastories)
+3. [Setting up Communities and Users](#setting-up-community-instances-and-users)
 
-4. [Demo and Tutorials](#demo-and-tutorials)
+4. [Customize Terrastories](#customize-terrastories)
 
-5. [Developing with Terrastories](#developing-with-terrastories)
+5. [Demo and Tutorials](#demo-and-tutorials)
 
-6. [Contributing Guidelines](#contributing)
+6. [Developing with Terrastories](#developing-with-terrastories)
+
+7. [Contributing Guidelines](#contributing)
 
 ## About Terrastories
 
@@ -25,7 +27,7 @@ Learn more about Terrastories at [https://terrastories.io/](https://terrastories
 ![](terrastories.gif)
 ###### *Terrastories: Matawai Konde 1.0 (October 2018)*
 
-## Setup
+## 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.
 
@@ -38,6 +40,14 @@ To install and run Terrastories for offline "Field Kit" usage, visit:
 
 4. [Setup for offline](documentation/SETUP-OFFLINE.md)
 
+## 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](documentation/COMMUNITY-SETUP.md).
+
 ## Customize Terrastories
 
 To set up Terrastories with a custom map, languages, visual assets, and to import data, see our [customization guide](documentation/CUSTOMIZATION.md).
@@ -63,7 +73,7 @@ We ♥ contributors! By participating in this project, you agree to abide by the
 ### 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](https://docs.google.com/document/d/1azfvU7tXLv2EHGrc3Hs5SPmB32MkyYuhXTB4JjymlV4/edit). 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. 
+One of our core contributors @mirandawang wrote a really nice [outline of the app](https://docs.google.com/document/d/1azfvU7tXLv2EHGrc3Hs5SPmB32MkyYuhXTB4JjymlV4/edit). 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](https://github.com/Terrastories/terrastories/wiki/Terrastories-Roadmap) to see where things are going with Terrastories development.
 
 **Step 2: Find an issue to work on**
 Please find an [issue](https://github.com/Terrastories/terrastories/issues) 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!
@@ -89,5 +99,5 @@ Try to keep your PRs limited to one particular issue and don't make changes that
 ### 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 Contributor
+### 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](https://t.co/kUtI3lnpW1), and find us in the channel #terrastories! :) 

documentation/COMMUNITY-SETUP.md

@@ -0,0 +1,38 @@
+# Setting up a Terrastories Community
+
+## Table of Contents
+
+1. [Why multi-instance architecture?](#why-multi-instance-architecture)
+
+2. [Setting up communities](#setting-up-communities)
+
+3. [Managing community users](managing-community-users)
+
+## Why multi-instance architecture?
+
+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.
+
+Additionally, it may become beneficial in the future to integrate and create hooks for Terrastories with other third party platforms that serve multiple communities using user credentials in a similar way.
+
+## Setting up communities
+
+Terrastories has a special administrative user credential 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 credential is for the management of communities exclusively.
+
+In the seed data that comes default with Terrastories, the default super admin credential is `[email protected]` 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. (There are two additional seed communities that come installed by default, `Terrastories` and `rfg`, which serve as examples and may be deleted.)
+
+When you create a community as super admin, you will be required to specify an `admin` login. This `admin` credential serves that community exclusively, and has the power to create new users, edit the community theme, and add/modify stories and data.
+
+## Managing community users
+
+There are currently four types of Terrastories users at the community level:
+
+1. `admin` - has permission to view, add, or modify `Stories`, `Speakers`, `Places` (restricted and non-restricted); add or modify `Users`; and change `Theme` settings.
+2. `editor` - has the permission to view, add, or modify `Stories`, `Speakers`, and `Places` (restricted and non-restricted).
+3. `member` - has the permission to view `Stories`, `Speakers`, and `Places` (restricted and non-restricted).
+4. `viewer` - has the permission to view `Stories`, `Speakers`, and `Places` (non-restricted only).
+
+The idea behind this architecture is to allow communities to determine who gets to edit manage the data, and who has access to restricted content. `members` can be understood as community members who can see all of the stories and places, whereas `viewers` are non-community members who may only see a selection of the stories that the community has chosen to share with outsiders.
+
+It is in our roadmap to allow `admins` to set granulated viewing and editing permissions for each individual story per specific username credentials, instead of doing so on a binary community vs. outsider basis.

documentation/CUSTOMIZATION.md

@@ -12,19 +12,23 @@
 
 ### Map content
 
-Terrastories uses the Mapbox GL engine to serve maps. What this means is that Terrastories can either load maps from `Mapbox.com` directly, or load offline map tiles called `mbtiles` that were designed and styled in Mapbox.com's `Studio` environment.
+Terrastories uses the Mapbox GL JS engine to serve maps. What this means is that Terrastories can either load maps from `Mapbox.com` directly, or load offline map tiles called `mbtiles` that were designed and styled in Mapbox.com's `Studio` environment.
 
 For some use cases, it may be sufficient to use one of Mapbox's basic styles, such as OpenStreetMap (OSM) or imagery. The default map served by Terrastories is a light OSM map. 
 
 You may also opt to design your own custom map style using Mapbox Studio. For example, if you have your own GIS shapefiles, you can upload the shapefile content to [Mapbox Studio](https://www.mapbox.com/mapbox-studio/), and use the Studio interface to lay out the map. You have to have a Mapbox account to use Mapbox Studio (creating and designing maps using Mapbox Studio is free up to certain file size limitations). To learn how to use Mapbox Studio, you can refer to the manuals and tutorials made available by Mapbox [here](https://www.mapbox.com/help/studio-manual-tutorials/) or other resources on the web.
 
 To set the map style used by Terrastories, modify the `MAPBOX_STYLE` variable in the `.env` file in the main Terrastories directory. You can copy and paste your map style URL from Mapbox Studio if using an online map.
 
+You can also set a `Mapbox.com` map for a community in the `Theme` menu when logged in as an admin user. Paste in the map style URL, and your map token, in the fields and it will automatically update the map for that community instance.
+
 For offline "Field Kit" usage of Terrastories, it is necessary to create your own custom map using your own GIS data, as above. There are several additional steps to generate and style the `mbtiles`, described in the [SETUP-OFFLINE.md](SETUP-OFFLINE.md) file.
 
+_**Note:** when using Mapbox.com maps with Terrastories, you are subject to Mapbox's [pricing schema](https://www.mapbox.com/pricing/) which has a free tier of up to 50,000 map loads per month. If you anticipate more monthly loads than that, you can get in touch with Mapbox's community team at [email protected] to see what they can do to help._
+
 ### Map extent and zoom
 
-It is possible to set a custom map extent, zoom level, and boundaries of the Terrastories map. Currently, these values have to be set manually in the `\rails\app\javascript\components\Map.jsx` file. (It is in our roadmap to make this process easier by using the Terrastories user interface).
+It is possible to set a custom map extent, zoom level, and boundaries of the Terrastories map. Currently, these values have to be set manually in the `\rails\app\javascript\components\Map.jsx` file. (It is in our roadmap to make this process easier by using the Theme menu in the Terrastories administrative menu).
 
 * To set the default map center, enter your desired coordinates for `defaultCenter` (line 6)
 * To set the boundaries of the map (beyond which you cannot pan or zoom), set the maximum southwest and northeast coordinates in `defaultBounds` (line 7-9)
@@ -52,7 +56,9 @@ Once you are done, the language should be available the next time you start Terr
 
 ## Adding custom visual assets
 
-It is possible to add your own background image for the Welcome screen of Terrastories, logos, and favicon. Navigate to `\rails\app\assets\images` and copy over your own images, replacing the relevant filenames of the files in this directory. (It is in our roadmap to make this process easier by using the Terrastories user interface).
+You can add your own background image for the Welcome screen of Terrastories, logos, and favicon. Navigate to `\rails\app\assets\images` and copy over your own images, replacing the relevant filenames of the files in this directory.
+
+It is now also possible to customize the background image and sponsor logos for a community via the `Theme` menu when logged in as an admin user.
 
 ## Importing data into Terrastories
 

documentation/SETUP-LINUX.md

@@ -91,8 +91,9 @@ docker-compose up
 
 You can view the running application at `localhost:3000`
 
-It will take a moment to load when first opening the application 
+It will take a moment to load when first opening the application.
 
+Once you have started Terrastories, the next step will be to set up Terrastories communities and users. Please see the [community setup guide] (CUSTOMIZATION.md) to proceed from here.
 
 ## Having troubles? Check our common errors & gotchas
 

documentation/SETUP-MAC.md

@@ -97,7 +97,9 @@ docker-compose up
 
 You can view the running application at `localhost:3000`
 
-It will take a moment to load when first opening the application 
+It will take a moment to load when first opening the application.
+
+Once you have started Terrastories, the next step will be to set up Terrastories communities and users. Please see the [community setup guide] (CUSTOMIZATION.md) to proceed from here.
 
 ## Having troubles? Check our common errors & gotchas
 

documentation/SETUP-WINDOWS.md

@@ -99,7 +99,9 @@ docker-compose up
 
 You can view the running application at `localhost:3000`
 
-It will take a moment to load when first opening the application 
+It will take a moment to load when first opening the application.
+
+Once you have started Terrastories, the next step will be to set up Terrastories communities and users. Please see the [community setup guide] (CUSTOMIZATION.md) to proceed from here.
 
 ## Having troubles? Check our common errors & gotchas