Add CONTRIBUTING.md
This commit is contained in:
Gautier P
parent
b181649dff
commit
db87c170be
3 changed files with 122 additions and 87 deletions
44
CONTRIBUTING.md
Normal file
44
CONTRIBUTING.md
Normal file
|
|
@ -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).
|
||||
71
INSTALL.md
Normal file
71
INSTALL.md
Normal file
|
|
@ -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.<version>.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.
|
||||
94
README.md
94
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)).
|
||||
|
||||
|
||||
|
||||
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.<version>.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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue