Permalink
Fetching contributors…
Cannot retrieve contributors at this time
148 lines (97 sloc) 5.61 KB

Geotrek-rando documentation

This documentation is a work in progress.

Please apologize for non already existing page but don't miss the opportunity to contribute by doing your own pull request.

Go further by learning how to contribute to the main development.

Overview

Geotrek

Geotrek-rando is FLOSS dedicated to display geographic and touristic contents.

These contents may be provided by linking this app either to the API of a Geotrek-admin instance or directly to static datas generated by a Geotrek-admin instance (Cf. [data source][]).

Geotrek-rando is build as a [Single Page Application][SPA] using AngularJS as main application framework, Leaflet for displaying the maps, and many other smaller libraries and utilities. Everything is bound as a single javascript bundle using Browserify, managed through Gulp tasks.

History

The first version (v1) was builded on top of Django framework, like Geotrek-admin. But maintaining such a backend application was a kind of lose of time with no added value. Since the second version, Geotrek-rando is now a [Rich Internet application][RIA] which has a very small hosting footprint.

Prerequisites

As Geotrek-rando works as a [SPA][], you only need an http server like [Nginx][] or Apache. (Cf. http server)

You'll also need to build the javascript main bundle which require [nodejs and npm][node]* to be available on the building environment. (Cf. Installing NodeJS)

Building environment could be either the same as your http server, or a local machine from which you'll sync generated files to the main server instance

* In recent versions of Geotrek-rando, you'll find the recommended version of Node JS into the .nvmrc file in the root directory of the project.

### For developpers

Some npm packages used for tests may need a build environment for compiling platform specific binaries. On debian-like environments, build-essential should satisfy this requirements.

See contribute section for more details about participating to Geotrek-rando development.

Install

Download and extract latest release of Geotrek-Rando from GitHub.

You may also download sources by cloning git repository.

Install build dependencies

cd Geotrek-rando-*
npm install

Launch build task

npm run dist

It will :

  • Create missing config files
  • Create the main JavaScript bundle as dist/public/scripts/rando.js
  • Compile sass files and bundle them in dist/public/styles/rando.css and dist/public/styles/rando-vendors.css

For automaticly building bundles when editing files, use :

npm run watch

Software update

Download and extract the latest release of Geotrek-Rando from GitHub (https://github.com/GeotrekCE/Geotrek-rando/releases).

Before upgrading, READ CAREFULLY the release notes, either from the CHANGES files or online.

wget https://github.com/makinacorpus/Geotrek-rando/archive/X.Y.Z.zip
unzip X.Y.Z.zip

In order to avoid editing NGINX configuration at each upgrade, you can rename the folders.

mv /path/to/application/ /path/to/application.old/
mv /path/to/Geotrek-rando-X.Y.Z/ /path/to/application/

Make sure the NGINX virtualhost refers to the folder of this new version.

Install the new version of the application.

cd /path/to/application/
npm install

Copy the custom folder of the previous version.

cp -aR ../previous-version/custom/ .

Launch build task

npm run dist

Settings & customization

Most of the settings (mainly everything about contents) has to be done directly in Geotrek-admin, but some parameters regarding Geotrek-rando have to be set up in a specific file. (Cf. Settings)

There is also a way to adjust the look and feel of the user interface by creating some specific files which will be used in place of defaults. For exemple: you could have your own header or footer files allowing you to include new elements without having to make change* to Geotrek-rando core files. (Cf. Customization)

NB: Each time you add, delete or modify a setting or a customization file, you have to rebuild the main javascript bundle.

* Making changes to core files of Geotrek-rando could prevent the possibility of upgrading it without losing your changes.

About FLOSS

If you're wondering what means Libre in FLOSS, it essentially imply four freedoms :

  • The freedom to run the program for any purpose.
  • The freedom to study how the program works, and change it to make it do what you wish.
  • The freedom to redistribute copies so you can help your neighbor.
  • The freedom to improve the program, and release your improvements (and modified versions in general) to the public, so that the whole community benefits.

[Nginx]: http://nginx.org/) [node]: https://nodejs.org/ "NodeJS" [RIA]: https://en.wikipedia.org/wiki/Rich_Internet_application [SPA]: https://en.wikipedia.org/wiki/Single-page_application "Single Page Application"