diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5e010271 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing + +BRouter is heavily based on the following libraries: + +- [Leaflet](leafletjs.com/) maps library, used in conjuction with many plugins. +- [Bootstrap](https://getbootstrap.com/) design library. +- [JQuery](https://jquery.com) javascript library. +- [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/en/). + +## Install dependencies + + yarn + +## Build + +```sh + #for development + yarn build debug + + #for release + yarn build +``` + +## Develop + + yarn serve + +## Translations + +`TL;DR` if you contribute to BRouter and add some translatable content, please make sure not to modify anything in `locales` folder, except `locales/en.json`. Full explanation below. + +### How internationalization works + +BRouter is translated using [i18next](https://www.i18next.com/) library, via command `gulp i18next`. It extracts translatable elements into `locales/en.json` file (English version). + +As soon as this file is modified, it must be uploaded to Transifex (manually) with the command `yarn push-transifex`. + +Anyone can then translate BRouter directly on [Transifex](https://www.transifex.com/openstreetmap/brouter-web/) platform. + +From time to time (eg. when preparing releases), we can update translated content with the command `yarn pull-transifex`. **It will overwrite all JSON files in `locales` directory**. + +## License + +BRouter is licensed under [MIT](LICENSE). Please make sure before adding any library that it is compatible with that. (GPL licenses are incompatible for instance). diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..0e4eb1a5 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,71 @@ +# Installation + +As an alternative to the [online version](https://brouter.de/brouter-web/), the standalone server of BRouter can also be run on your local desktop. + +## Install standalone zip (client and server) + +1. download and unzip latest standalone archive (`brouter-web-standalone..zip`) from https://github.com/nrenner/brouter-web/releases e.g. for Linux (replace `~/opt/` with your preferred install directory and `0.11.0` with latest version): + + mkdir ~/opt/brouter + cd ~/opt/brouter + wget https://github.com/nrenner/brouter-web/releases/download/0.11.0/brouter-web-standalone.0.11.0.zip + unzip brouter-web-standalone.0.11.0.zip + +2. download one or more [data file(s)](https://brouter.de/brouter/segments4/) (rd5) into `segments4` directory + +### Configure BRouter-Web + +In the `brouter-web` subdirectory: + +1. copy `config.template.js` to `config.js` +2. add your API keys (optional) + copy `keys.template.js` to `keys.js` and edit to add your keys + +### Run + +1. start `./run.sh` + +## Running as Docker container (client only) + +brouter-web can be run as a Docker container, making it easy for continous deployment or running locally +without having to install any build tools. + +The `Dockerfile` builds the application inside a NodeJS container and copies the built application into a +separate Nginx based image. The application runs from a webserver only container serving only static files. + +### Prerequisites + +- Docker installed +- working directory is this repository +- `config.template.js` copied to `config.js` and modified with a Brouter server, see `BR.conf.host` +- `keys.template.js` to `keys.js` and add your API keys +- Optionally create `profiles` directory with `brf` profile files and add path to `config.js`: + BR.conf.profilesUrl = 'profiles/'; + +### Building Docker image + +To build the Docker container run: + + docker build -t brouter-web . + +This creates a Docker image with the name `brouter-web`. + +### Running Docker container + +To run the previously build Docker image run: + + docker run --rm --name brouter-web \ + -p 127.0.0.1:8080:80 \ + -v "`pwd`/config.js:/usr/share/nginx/html/config.js" \ + -v "`pwd`/keys.js:/usr/share/nginx/html/keys.js" \ + -v "`pwd`/profiles:/usr/share/nginx/html/profiles" \ + brouter-web + +This command does the following: + +1. Runs a container with the name `brouter-web` and removes it automatically after stopping +1. Binds port 80 of the container to the host interface 127.0.0.1 on port 8080 +1. Takes the absolute paths of `config.js`, `keys.js` and `profiles` and mounts them inside the container +1. Uses the image `brouter-web` to run as a container + +brouter-web should be accessible at http://127.0.0.1:8080. diff --git a/README.md b/README.md index 3e6cbb56..a1fe0b2b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # brouter-web -Web client (by [@nrenner](https://github.com/nrenner) and [contributors](https://github.com/nrenner/brouter-web/graphs/contributors)) for the BRouter routing engine (by [@abrensch](https://github.com/abrensch)). _Work in progress_. +Web client (by [@nrenner](https://github.com/nrenner) and [contributors](https://github.com/nrenner/brouter-web/graphs/contributors)) for the BRouter routing engine (by [@abrensch](https://github.com/abrensch)). + +![demo](https://user-images.githubusercontent.com/1451988/83979926-1f6d8c80-a912-11ea-8f21-b2ed60963501.gif) Instances: @@ -8,6 +10,7 @@ Instances: - [brouter.damsy.net](https://brouter.damsy.net) _(provided by [@bagage](https://github.com/bagage))_ **This repository is only about the frontend**. + For the server/backend, BRouter routing engine, Android app, profiles, [brouter.de](https://brouter.de) site, see: https://github.com/abrensch/brouter @@ -31,100 +34,17 @@ click **Translate** to start translating. ## Installation -As an alternative to the above online version, the standalone server of BRouter can also be run on your local desktop. - -### Install standalone zip (client and server) - -1. download and unzip latest standalone archive (`brouter-web-standalone..zip`) from https://github.com/nrenner/brouter-web/releases e.g. for Linux (replace `~/opt/` with your preferred install directory and `0.11.0` with latest version): - - mkdir ~/opt/brouter - cd ~/opt/brouter - wget https://github.com/nrenner/brouter-web/releases/download/0.11.0/brouter-web-standalone.0.11.0.zip - unzip brouter-web-standalone.0.11.0.zip - -2. download one or more [data file(s)](https://brouter.de/brouter/segments4/) (rd5) into `segments4` directory - -#### Configure BRouter-Web - -In the `brouter-web` subdirectory: - -1. copy `config.template.js` to `config.js` -2. add your API keys (optional) - copy `keys.template.js` to `keys.js` and edit to add your keys - -#### Run - -1. start `./run.sh` - -### Running as Docker container (client only) - -brouter-web can be run as a Docker container, making it easy for continous deployment or running locally -without having to install any build tools. - -The `Dockerfile` builds the application inside a NodeJS container and copies the built application into a -separate Nginx based image. The application runs from a webserver only container serving only static files. - -#### Prerequisites - -- Docker installed -- working directory is this repository -- `config.template.js` copied to `config.js` and modified with a Brouter server, see `BR.conf.host` -- `keys.template.js` to `keys.js` and add your API keys -- Optionally create `profiles` directory with `brf` profile files and add path to `config.js`: - BR.conf.profilesUrl = 'profiles/'; - -#### Building Docker image - -To build the Docker container run: - - docker build -t brouter-web . - -This creates a Docker image with the name `brouter-web`. - -#### Running Docker container - -To run the previously build Docker image run: - - docker run --rm --name brouter-web \ - -p 127.0.0.1:8080:80 \ - -v "`pwd`/config.js:/usr/share/nginx/html/config.js" \ - -v "`pwd`/keys.js:/usr/share/nginx/html/keys.js" \ - -v "`pwd`/profiles:/usr/share/nginx/html/profiles" \ - brouter-web - -This command does the following: - -1. Runs a container with the name `brouter-web` and removes it automatically after stopping -1. Binds port 80 of the container to the host interface 127.0.0.1 on port 8080 -1. Takes the absolute paths of `config.js`, `keys.js` and `profiles` and mounts them inside the container -1. Uses the image `brouter-web` to run as a container - -brouter-web should be accessible at http://127.0.0.1:8080. +See [INSTALL.md](INSTALL.md) for guidance on installation. ## Build -### Dependencies - -Requires [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/en/). - -### Install - - yarn - -### Build - - yarn build #for release - yarn build debug #for development - -### Develop - - yarn serve +See [CONTRIBUTING.md](CONTRIBUTING.md) for development documentation. ## License Copyright (c) 2018 Norbert Renner and [contributors](https://github.com/nrenner/brouter-web/graphs/contributors), licensed under the [MIT License (MIT)](LICENSE) -## Credits and Licenses +### Credits and Licenses - [BRouter](https://github.com/abrensch/brouter) (not included) by abrensch; [GNU General Public License, version 3.0 (GPLv3)](https://github.com/abrensch/brouter/blob/master/LICENSE)