🌐 Hosting Terrastories online
This page may require some technical knowledge about server hosting and deployment. If the content of this page feels unfamiliar to you, get someone acquainted with information technology (IT) to help you.
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-buildpackheroku/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.
Last updated