Most developer contributions will be focused on the rails app. Because this project uses docker, we already have a uniform ruby/rails development environment in our rails docker image. Any time you need to run a rails command you should do so from a running docker container to take advantage of this consistent environment. Use the following command to open a bash console on the rails container:
$ docker-compose exec web /bin/bash
Now you can treat this console like any other development environment, running rails or bundler commands as needed. Please refrain from running such commands in your local environment. Always use the rails container instead.
Any changes to source files should be made directly in your local filesystem under the
/opt/terrastories directory using your preferred editing tools.
Terrastories offline mode is generally used in the field, when there is no access to the internet.
In those cases, before starting the server, add USE_LOCAL_MAP_SERVER=true to your .env file. Remove this variable to go back to using mapbox.
In order to get the local tileserver map running, you will also need to download this mbtiles and place it in tileserver/data/mbtiles/basic.mbtiles
And instead of running docker-compose up, run
script/run_offline_maps.shIn the Terrastories back end, it is possible to import data in bulk using a CSV importer.
The data should be imported in the following order: Places, Speakers, and then Stories.
To prepare CSVs for importing, use the following workflow to ensure that character diacritics are properly imported:
-If the file is already an .xlsx, go to Google Sheets and File->Import from the menu. Then import the file. -Otherwise create the file directly in Google Sheets. Make sure the file has a row for headers. -Go to File -> Download As-> Comma Separated Values, and save the file to your machine. -This CSV should be properly encoded as UTF-8. It's best to verify this with Notepad++ instead of Excel if you are on a Windows machine.
Terrastories stores Places, Speakers, and Stories in a database (Postgres DB). it is possible to back these data up and restore them by running lines of code in a bash terminal.
Using Powershell:
Backup the DB in PS with:
docker run --rm -v "terrastories_postgres_data:/pgdata" -v "$(pwd):/host" busybox tar -cvzf /host/db-backup-test.tgz -C /pgdata .
Restore a backup in PS with:
docker run --rm -i -v "terrastories_postgres_data:/pgdata" -v "$(pwd):/source/" busybox tar -xvzf /source/db-backup.tgz -C /pgdata
Note: the above code is assuming your build is called terrastories. It may be necessary to run docker volume ls to get the right Docker container name ending with _postgres_data.
Terrastories uses internationalization to translate the application's core text, like the welcome page, sidebar, and administrative back end content. We have made it easy to add new languages to Terrastories without needing to touch any of the code.
To add a language to Terrastories, navigate to the rails/config/locales/ directory. Within this directory, each language has it's own subdirectory, like en (English) or pt (Portuguese). Currently, there are three files in each (using Portuguese as an example):
pt.ymldevise.pt.ymladministrate.pt.yml
pt.yml contains the custom text used in the Terrastories application. devise.pt.yml and administrative.pt.yml are used by the administrative back end.
To set up a new language, create a new subdirectory in the locales folder. Let's assume you want to set up Papiamentu. Create a subdirectory called pap and copy over en.yml from the en folder. Rename it to pap.yml, change line 32 to pap, and translate each line of text in what follows.
For the devise and administrate files, there might be available translations already available online for common Western languages. If so, you can download these and place them in the directory, and make sure that the language code is consistent (for languages like Spanish and Portuguese, the language code might sometimes have a country-specific suffix like pt-BR). If translations are not available, do the same thing with these two files as translating en.yml.
If you want to change the default language for Terrastories, set the language on line 21 in rails/config/application.rb. To set it to Papiamentu, change this line to config.i18n.default_locale = :pap
Once you are done, the language should be available the next time you start Terrastories.
We use ESLint with Airbnb community style-guide for linting JavaScript and JSX for files under app/javascript.
Please check ESLint editor-integrations page to read about how to integrate ESLint with your IDE/editor
You can run e2e tests with
script/test