The Earth Defenders Offline Toolkit is intended to be used by a group that has a common physical meeting space, which is the coverage area of the device's wifi. That coverage area can be small or large depending on the devices wifi radio, but can expand to cover large areas, such as villages, by connecting them to routers and expanded through mesh networks.

Offline Toolkit is meant to help groups onboard new users to the tools curated on the Earth Defenders Toolkit platform, as well as provide common helpful assets and helper applications for these tools. It can also assist organizing data in a local offline environment, and provide ways to sync and share data locally or through the Internet. It's also a great tool for partner organizations to organize and synchronize data with the ground communities.

Some Offline Toolkit devices (such as single-board-computers) are small, but aren't so fragile, and with appropriate casing, they can easily travel within a backpack together with clothes.

The toolkit can be used mobile, during meetings or fieldwork with the right power supply and weather protection.

It's also great for indoor spaces such as a house, a remote base or an office, as long as it’s protected from the weather and other possible hazards, such as children playing.

The current included tool workflows are participatory mapping with Mapeo, and land-based story telling with Terrastories. These workflows are meant for:

• on-boarding new users to the tools through config files, map tiles etc.

• providing mobile and desktop installers for the tools

• providing bridging services between the tools

• providing documentation and use cases for the tools

• providing running instances of the tools, such as Mapeo and Terrastories

• providing local storage for organization data (documents, photos, videos, folders, etc.)

• providing p2p syncing of the stored data, locally or remotely

• providing a way for all content to be updated whenever device is connected to the Internet

Even on offline environments, devices (mobile or desktop) in good range of the WiFi created by the Offline Toolkit computer will have access to:

• All content on the EDT platform: guides on community protocols and curated tools, as well as stories from communities from around the world on their experience using the tools

• Installers for curated tools

• An interactive map showing Mapeo observations that have been synced with device

• File browsing application for storing and sharing files, similar to Google Drive

• Automatic syncing of default content (scrapped websites, application installers, Mapeo configs, map tiles)

• Automatic creation of files that can be imported into Terrastories, from synced Mapeo observations

A computer running EDT offline creates a hotspot, where people with devices in wifi range can download, install, and use applications curated on the Earths Defender’s Toolkit platform. We've organized content around topics such as community mapping and land-based storytelling. For each of these topics we provide guides, use cases, assets and helper applications, which are made available through a simple interface.

On the local network, community members have access to applications for storing and sharing their content. The featured tool Terrastories can also be used locally.

Make sure you have a device that was previously setup with the Earth Defenders Offline Toolkit.

If your device has an external WiFi card, connect the card to the device before turning it on. If there are external antennas, make sure to connect them.

Connect the device to the power supply and make sure the device is turned on by checking that the lights are on. If there's an external WiFi card, it should also turn on.

After a couple of minutes, verify that the WiFi hotspot appears on the user's devices. Connect to the hotspot and open the captive portal (for desktops, the captive-portal may not show).

Finally, with the portal open, copy the provided URL, open your preferred browser, paste the URL and load the page. You're ready to start exploring.

If some content isn't showing up, it might be that you're device hasn't synchronized content yet. To synchronize content with the Earth Defenders Toolkit Cloud, you must first connect your device to the Internet and then contact us for authorization.

For detailed instructions check the manual:

Continue with guides on:

• Connecting to the internet

• Syncing content

• Exploring content

There are currently 3 toolkits pre-loaded and running:

• Mapping and Monitoring

• Land-based storytelling

• Local Community Cloud

Each toolkit has links or downloads for the applications, as well as documentation and community stories around the tool usage.

The default username is admin and password is admin123.

The first time a device is connected it’ll send a request to Earth Defenders Toolkit Cloud to start syncing content. Get the ID from the the local Offline Toolkit Syncthing instance:

Get in touch with us on Supportand send along your Syncthing ID along with other information.

Once we authorize syncing from the EDT Cloud the local Offline Toolkit should start displaying syncing information:

Syncing can take a while because it's a few gigabytes of content. Once that's done, all content should be ready for offline use.

The recomended and easiest way to connect any Offline Toolkit device to the Internet is through ethernet cable, directly from the router to the device.

Your device can connect to a local WiFi hotspot in order to gain access to the internet, but this feature hasn't been well tested as of yet.

The device will scan for nearby wifi hotspots. You can then select the one to connect to, enter the password and connect.

Does my community or organization have full control and ownership over data stored on an EDT Offline device?

Can I install EDT Offline in any computer?

The interface for the Mapeo Data Hub is a map displaying the observations that has been synced. Because this can be dangerous we display only the markers, and no information more.

Feedback is welcome on how to safely build this in a way that's useful.

First connect to the Offline Toolkit's WiFi hotspot, or to a wifi network that it's also connected too.

You should see the Offline Toolkit device showing up and ready to sync.

If not you might need to change your project key. In case you don't have an existing project, download and use the custom Mapeo configuration that's provided, which comes preset with the same project key as the Hub.

If you already have a custom project key check Customization to learn how to set the correct key for the Mapeo Data Hub to work for your team.

On the configuration file included with the Offline Toolkit there's a Terrastories category. Every observation marked with it will be processed by the Mapeo Data Hub and placed on a csv file formatted for Terrastories.

Once imported into Terrastories, the obversations will be available as Places, and ready to be used to link to Stories and Speakers.

A custom application that can be used for:

• Synchronizing Mapeo data from local devices, see Syncing with Hub

• Displaying all observation data on a local offline map, see Observations map

• Generating a compatible csv file that can be import into Terrastories as a Story Place, see Mapeo Observations as Terrastories Places

Mapeo Data Hub

Is a custom made application for the Offline Toolkit that intends to enable bridging content from Mapeo to Terrastories, as well as providing a better experience for Mapeo users.

Pataka

Terrastories

File management

Content syncronization

It can be customized to sync other folders by default, or used to sync any folder on the device. There are also mobile and desktop applications to sync with any device easily.

Application installers

A simple custom made application that displays the installers for curated applications.

Tile server

Pataka is an application designed to be run as an always online peer. Ideally this peer is set up with a static, public IP address, (or port forwarding from one).

This peer is not able to decrypt any messages (or file) that are private to groups, but will replicate these messages (and files) to ensure they are accessible even when the creator is offline, or so there is a backup.

You're project might have a secret key already setup, and so your Mapeo device isn't able to find the Mapeo Hub locally.

Check Customizing experiencefor instructions on how to change variables.

You can change project key for Mapeo: MAPEO_PROJECT_KEY

Add your projects key which can be obtained from the Mapeo sync screen.

Change Mapeo category that Terrastories place's will be collected from: MAPEO_TERRASTORIES_TYPE

Every observation of that category will be included in the csv with Story Places for Terrastories to import.

To start using Earth Defenders Offline Toolkit you'll need to setup a computer to run the software. If you already have one, proceed toDevice usage.

There are several supported devices and ways to setup computers to run the Offline Toolkit. Head to the Device setup section to understand how this works.

If your team lacks the necessary technical skills to setup your own device, please get in touch with our team at Digital Democracy so we can assist you on choosing the best path to deploy a device for your community or organization.

The Offline Toolkit provides a storage space for community data. Besides the administrator, all other content is public.

The first step is creating a new account for yourself. You'll need to memorize your name and password.

Once logged in you'll have acces to the public space for storing files. Create a personal or team folder and store your files inside.

Be mindful of storage space as there are limits to how much the device can hold. Check Managing device to learn how to check storage space.

With the bundled Filebrowser application, community members can create their own accounts, upload and download files from a shared digital space.

An administrator can manage users, and different settings and have private content.

The default username is admin and password is admin123.

Check guides on:

Everyone loggede to the community cloud has access to all folders. But in case you want to share a file with someone who isn't part of the community through the local network, you can use the Share functionality of the file browsing application.

Select the duration of the share, and if a password is needed, and finally click Share:

Copy the address and share it through other means such as a chat app.

We can start by adding a folder from our community cloud:

Add a descriptive label to the new folder. The content directory is named /config here, so find your folder under it.

Before clicking save, go to the Advanced tab. Change the Folder Type according to your needs.

For the cloud, Send Only is worth selecting, as most times we want a single source of truth for the content

Finally we can click save.

Installers for all major systems are provided: Android, iOS, Windows, Mac and Linux.

If the installer isn't available for your system, it's because it doesn't exist.

With it it's possible to:

• Check device name

• Check RAM and CPU usage

• Check other various information relatede to your device

• Restart or shutdown the device

• Manage running services

• Explore files similar to Filebrowser

• Connect to a WiFi hotspot

• Set custom variables

⚠️ Beware that during Beta we're relying on the service Balena Cloud by a company, and they have back doors to all devices.

The process for preparing a device to run Earth Defenders Offline Toolkit requires a notebook or desktop computer, used to "burn" images to sd cards or usb flash drives. So basic skills on using them is required.

For help with common technical issues, see the Troubleshooting section of this guide. For additional help, see the Support section.

Different processes

Any old computer can be recycled to run the Earth Defenders Offline Toolkit software stack. Ideally you should format old machines to run our light Operating System, see Regular computers.

The Offline Toolkit can also run the services alongside your existing Operating System see Using Docker. This process is unsupported and disconnected from Balena Cloud, thus respects data sovereignty.

If the intention to purchase a new device for this purpose, we encourage buying a single-board-computer, as they tend to be cheaper, more mobile, uses less energy and are easier to setup, see Single-board-computers.

Supported Installations

The Digital Democracy team will have access to the device and all data, but will not access or extract data without consent. We'll monitor devices for software and hardware problems, so we can provide support.

But the Balena company will also have backdoors into the device, which most probably won't be used, but can be used.

We currently generate supported ready-to-use images that can be flashed into any regular computer and selected single-board-computers.

Continue to Choosing a device to find the best fit for your needs.

Unsupported installations

You'll generate your own image, but running our software. That way you can manage your own fleet of devices.

Check Connecting to the internet and Syncing content to learn how to get the content for your Offline Toolkit.

You'll still need to get in touch with us at least to authorize syncing the content, see Support.

⚠️ Attention! The administration interface can only work while the device is connected to the internet for now.

On the initial page there's several information on the devices's usage: processing, memory, storage as well as other importante information such as cpu temperature. Select the menu to explore other functionality.

In order to customize the device, enter the Configuration page:

On that page you can change the Environment Varibles for customization.

For example, the base maps for Terrastories,and the Observations Map can be changed by changing the OFFLINE_MAP_STYLE variable:

The device's default edt.local adress can be changed by changing the hostname:

The device's will now be acessible via http://mygroup.local

When changing hostname other variables need to changed to reflect the new addresss: SET_HOSTNAME, HOST_HOSTNAME, OFFLINE_MAP_STYLE

By setting values to specific variables we can change some behaviors, such as:

• Change WiFi SSID (hotspot name): PWC_HOTSPOT_SSID

• Change WiFi password: PWC_HOTSPOT_PASSWORD

• Change device's address: SET_HOSTNAME

• Change default username for Filebrowser and Syncthing: ADMIN_LOGIN

• Change default password for Filebrowser and Syncthing: ADMIN_PASSWORD

• Change project key for Mapeo: MAPEO_PROJECT_KEY

• Change Mapeo category that Terrastories place's will be collected from: MAPEO_TERRASTORIES_TYPE

• Should be set according to SET_HOSTNAME in order for Terrastories to work properly: HOST_HOSTNAME

• The offline map that Terrastories will use: OFFLINE_MAP_STYLE

Syncing content

Sync source

The source Syncthing instance that the device will sync from

• SYNC_SOURCE_ID

• SYNC_SOURCE_NAME

Crawled websites

• SYNC_CRAWLS_ID

• SYNC_CRAWLS_NAME

Mapeo configurations

• SYNC_MAPEO_ID

• SYNC_MAPEO_NAME

Map tiles

• SYNC_TILES_ID

• SYNC_TILES_NAME

F-Droid repository

• SYNC_FDROID_ID

• SYNC_FDROID_NAME

Application installers

• SYNC_INSTALLERS_ID

• SYNC_INSTALLERS_NAME

• What's Balena

The Earth Defenders Toolkit Cloud is a code-as-infraestructure meant to be used by Digital Democracy's project team as well as replicated by other organizations giving support to communities.

The purpose of these servers is to bootstrap and update content for instances of the Earth Defenders Toolkit Offline, and as they have high availability.

There are a multitude of different boards that can be used to run EDT Offline. From recycled hardware, such as old computers to tiny, low-power single-board-computers.

Some important things to pay attention when choosing the right device:

• Ease to setup (single-board-computers are always easier)

• Price, including power supply, storage, case, etc.

• WiFi range and capacity

• Energy usage

• Power

• Availability

• Form factor

Easiest to setup, but more expensive and less CPU and WiFi power

Single-board-computers are the easiest to setup. We’ve tested on the Raspberry Pi 4 and Rock Pi 4, and had great results. The Raspberry 3 should be able to handle as well, but we haven’t tested yet.

Recommended: Rock Pi 4 B+

Besides the board itself you’ll need some cooling, as the boards tend to overheat without appropriate cooling system.

You’ll also need a power supply in case it isn’t included with the board, and it’s important that it’s a USB C 5v with at least 3A.

And finally you’ll need a storage, which should be at least class 10 micro-sd card.

Buying from Amazon:

Cheap, powerful CPU and WiFi, but harder to setup

Any old desktop of notebook can serve as an EDT Offline device, but they’re a bit harder to setup, and they usually require entering the computer’s BIOS and change some settings to set USB as primary device to boot from. That will require are least a key board and a screen, and appropriate cables to connect to it.

Turn the device off, insert the thumb drive, and turn it back on. This process can take minutes and might require a few restarts, but once finished will have a fully working EDT Offline instance.

It’s one of the cheapest boards you can get, with the smallest form-factor. It’s PCI express port makes it easy to plug different WiFi adapters, which will depend on how fast you want the connection to be, how many people it can handle at the same time and how far you need your WiFi hotspot to go.

Buying from Amazon

Full list of potential devices

Single Board Computers

Because they usually use ARM cpus they tend to be consume less energy and have a smaller form-factor, but are less capable, and don't usually include storage, casing or a cooling system

• • 4GB LPDDR4

  • RK3399 Hexa-Core

  • Gigabit Ethernet

  • Dual-Band WiFi

• • 1GB / 2GB / 4GB / 8GB LPDDR4

  • BCM2711 Quad-Core

  • Gigabit Ethernet

  • Dual-Band WiFi

• • Includes casing & power supply

  • 4GB LPDDR4

  • 32GB eMMC

  • BCM2711 Quad-Core

  • 2x Gigabit Ethernet

  • Dual-Band WiFi

• • 4GB LPDDR4

  • RK3399 Hexa-Core

  • Gigabit Ethernet

  • No WiFi included

• • Includes casing & power supply

  • 16GB / 32GB eMMC

  • 4GB / 8GB LPDDR4

  • Intel Celeron N3350

  • 2x Gigabit Ethernet

  • No Wifi, but 4x PCIe ports for dongle

• • 0 / 64GB / 128GB eMMC

  • 8GB LPDDR4

  • Intel Celeron J4125

  • 2x Gigabit Ethernet

  • Dual-Band WiFi

  • 2x M.2 PCIe

• Not confirmed Balena support

  • 16GB / 32GB eMMC

  • 2GB / 3GB LPDDR4

  • Amlogic S912 1.5 GHz 64Bit Octa Core ARM Cortex-A53 750MHz

  • Gigabit Ethernet

  • Dual-Band WiFi MIMO 🔥

Fanless Mini PCs

These tend to be cheaper and more powerful then SBCs, and come complete with storage, casing and power supply

• • 8GB DDR3

  • 128GB SSD

  • Intel Celeron

  • Gigabit Ethernet

  • Dual-Band WiFi

• • 4GB DDR4

  • 64GB eMMC

  • Intel Celeron

  • Gigabit Ethernet

  • Dual-Band WiFi

• • 4GB DDR

  • 64GB eMMC

  • Intel Celeron

  • Gigabit Ethernet

  • Dual-Band WiFi

• • 4GB - 8GB LPDDR4

  • 64GB - 512GB M.2 SSD

  • Intel Celeron

  • Gigabit Ethernet

  • Dual-Band WiFi

• • 4GB DDR4

  • 64GB eMMC

  • Intel Celeron

  • Gigabit Ethernet

  • Dual-Band WiFi

On regular machines the process is similar to formatting any computer. It's done through flashing a usb drive and getting it to boot through keyboard commands.

Recomended devices:

Needed hardware

• Any spare computer with a storage that you can format, like old desktop or laptop machines with a hard-drive or ssd with at least 30Gb of storage

• Any USB drive with at least 2Gbs of storage

• Internet connection through ethernet cable

• Keyboard

• Monitor and cables

Needed software

Preparing USB flash drive

Use the image burner to burn the image to the usb flash drive.

Installing the Offline Toolkit

• Insert the flashed USB into the computer

• Insert the ethernet cable with Internet coming from your router into the computer

• Discover how to trigger boot menu or how to enter BIOs and ajusting booting order

• Select boot to happen throgh UEFI or USB, and the device should start setup

• Setup can take several minutes depending on the computer's capabilities

• In case a long time has passed without anything happening, unplug and re-plug power supply

The process for a single-board-computer (SBC) is much simpler, and only requires burning an sd card.

Recomended devices:

Needed hardware

• Class 10 micro sd card with at least 32gb

• A computer with a sd card reader

• Internet connection through ethernet cable

Needed software

Preparing USB flash drive

Use the image burner to burn the image to the sd card.

Installing the Offline Toolkit

• Insert the flashed sd card into the computer

• Insert the ethernet cable with Internet coming from your router into the computer

Third party company will be managing a monitoring platform for your devices, and they have backdoors to your devices

Anyone can deploy there own EDT-Offline by following these steps:

2. You'll be asked to create a Balena Cloud account

3. You'll be prompted to deploy a new fleet, change the name if necessary and click on "create and deploy”

4. Click on the "Add device” button

5. Leave in "Production" mode unless you'd like to experiment and have ssh access to the device

6. To setup the device you'll need Internet, choose the way you intend to connect, either through WiFi (provide the credentials) or Ethernet cable

7. Finally either click "Flash" which will automatically flash using Etcher, or using the arrow click on "Download balenaOS", which will download the image file

8. Insert the storage in the computer and burn the image

10. To sync with default content you'll need to get in touch with us through e-mail, Telegram or Whatsapp

Using Docker EDT-Offline can be setup in almost any machine without any special operating system needed.

Needed installed software

These are the steps:

1. Clone repository

2. cd docker/local directory

3. cp .env.example .env

4. Edit .env with your own values

5. Run docker-compose up -d

6. Use docker-compose logs -f to see logs

• Balena: OS, Cloud

1. Web scrapping

Some experimentation is needed to find best practices on how to get exactly the amount of pages we want scraped, and for each language.

The scrapping might take a long time. Use the output warcz files on the next step.

2. Upload to the Cloud

There are different directories within the content directory, each for a content type: F-Droid repository data; Desktop installers; Mapeo data (configs and tiles); and Offline Websites.

Create a new folder for your new content if needed:

Make sure there’s enough left storage on the server, and to upload new content simply drag to the folder or use the upload icon to select the file from your computer:

Once the new content is uploaded we can sync it to EDT devices.

3. Sync it

4. Adding to device

Check instructions on Syncing contenton how to start syncing with a new device. You'll how to get your Syncthing ID.

On the EDT Cloud instance search for that ID:

Give the new device a descriptive name, and got to the Sharing page:

On the Sharing page select all the folders that are relevant for the new device, usually the defautls:

On EDT Cloud you should see that the device is starting to sync:

On the local Offline Toolkit you should also see syncing happening with more details such as download rate, and amount synced so far.

You're done. Now every time the Cloud updates the content folder, the Offline Toolkit devices will automatically sync whenever they're online.

Syncthing

The app is used for keeping up-to-date content (mapeo configs and tiles, offline websites, f-droid repository, etc) available for when community or organization devices go online.

The initial handshake between instance in the cloud and other devices is initialized automatically by the EDT Offline device, but needs to be accepted by someone with access to the Cloud service.

File Browser

Provides a file managing interface within a specified directory and it can be used to upload, delete, preview, rename and edit files. It allows the creation of multiple users and each user can have its own directory. It can be used as a standalone app. It's a FOSS alternative to Google Drive, without the office suites.****

It's used for browsing content both in the cloud as well as on the offline device. The team giving support to communities should use it to add or remove content that's hosted on the cloud. The offline devices can use it to share files back with the support team, or within the local network.

F-Droid Repository

F-Droid is an app store and software repository for Android. Applications can be browsed, downloaded and installed from the client app without the need to register for an account. It's a FOSS alternative to the Google Play store.

Regular F-Droid clients can also make use of the EDT repository by simply adding the url to their list of repositories or scanning the QR code presented.

Secure Scuttlebut Room

The SSB Room is a service that enables peers to “meet” online and exchange data. By running our own Room we can connect partners between themselves as well as support teams. It has user management features (allow- & denylisting + moderator & administrator roles), all administered via the web dashboard.

Minio Storage

MinIO is a high performance object storage solution that provides an Amazon Web Services S3-compatible API and supports all core S3 features. It’s a FOSS alternative to Amazon S3.

It's used for organizing Terrastories data into buckets. That way if a partner wants to have it’s Terrastories published on the cloud, we can sync it’s Minio bucket, which is running on the EDT Offline device, and run a Terrastories instance on the cloud pulling from that data. It provides an organized way of maintaining online and offline Terrastories instances in sync.

• Github Actions

Tunneling to a development device

SSH into the virtual Balena device using the UUID which can be obtained from the Balena dashboard:

balena ssh <uuid>

Within the virtual Balena environment, run:

And to start the tailscale service, run:

The Tailscale container will provide you a URL to access that adds the device to your Tailscale account.

On your own machine run:

And to start tailscale:

Don't forget to also enable the subnets. And now on your machine you should be able to access services on the balena device's ip.

Using remote device

In order for Terrastories and the offline map on both Terrastories and Observations Map to work remotely you'll need to set the device's variables to use the tunneled ip:

• HOST_HOSTNAME ex.: 100.96.14.113

• OFFLINE_MAP_STYLE ex.: http://100.96.14.113:8085/styles/terrastories-map/style.json

Setting up a virtual-machine

Make sure you have a Balena Fleet with generic x86_64 (GPT) as the Default device type.

On a Digital Ocean droplet with at least 25Gbs of storage and 1Gb of ram, and latest Docker pre-installed, run:

After a few seconds a new device should appear on your amd64 and should start updating itself with latest release for the Fleet.