Terrastories Support Materials
  • Introduction
  • OVERVIEW
    • About Terrastories
      • How Terrastories is being used
    • FAQs
    • Getting started
    • Terrastories demo
  • USING TERRASTORIES
    • Exploring the Terrastories main interface
    • Using the Terrastories member dashboard
      • Exploring and creating stories, speakers, and places
      • Customizing your community theme
      • Setting up users and roles
      • Setting up an Explore Terrastories view for your community
      • Modifying map settings
      • Importing data
  • EXPLORE TERRASTORIES
    • What is Explore Terrastories?
    • Exploring the Explore Terrastories interface
    • Setting up Explore Terrastories for your community
  • Operating Terrastories Offline
    • Operating an offline Terrastories "Field Kit"
    • Preparing offline map packages
  • SETTING UP A TERRASTORIES SERVER
    • Hosting environments
      • 🌐 Hosting Terrastories online
      • 🛖 Hosting Terrastories offline as a "Field Kit"
        • Advanced Setup
      • 🍫 Hosting Terrastories on Kakawa (Earth Defenders Toolkit Offline)
    • Navigating the Super Admin dashboard
    • Setting up an Explore Terrastories server
  • MISCELLANEOUS
    • Support
    • Troubleshooting
      • Offline map tiles are not showing up
      • Resetting passwords (using the Rails console)
      • Saving and printing Terrastories reference materials
    • Translating Terrastories
    • Additional resources and references
    • For developers
  • Terrastories website
  • our.terrastories.app
Powered by GitBook
On this page
  • Prerequisites
  • Install Terrastories
  • Additional steps for configuration
  • Bringing Terrastories offline
Export as PDF
  1. SETTING UP A TERRASTORIES SERVER
  2. Hosting environments

🛖 Hosting Terrastories offline as a "Field Kit"

Previous🌐 Hosting Terrastories onlineNextAdvanced Setup

Last updated 1 year ago

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

It is possible to install Terrastories on Windows or Mac OS; however, this workflow has only been fully tested on a Linux OS. You may need to take different steps for some of the setup depending on the operating system; for example, the hosts and Hotspot network manager files may reside in a different location.

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

Quick Install sets up a new database and utilizes Terrastories default map style. If you wish to use your own map style, please see for more information.

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

At this point, you may bring your "field kit" offline.

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

Make sure none of your WiFi connections are enabled to connect automatically.

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

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

Set Docker to operate without sudo access

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.

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 .

Here is a , if needed.

Here is a , if needed.

documentation for developers on Github
advanced setup
our Github repository
guide for bypassing login screen on boot
guide for configuring Docker to start on boot
guide for configuring Docker to operate without sudo