🛖 Hosting Terrastories offline as a "Field Kit"
Last updated
Last updated
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 .
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
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:
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):
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 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
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:
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:
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:
Save and close the file, and run:
You are now ready to bring Terrastories to an offline context!
From here, you can run the command:
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.
