diff --git a/docs/administration.md b/docs/administration.md new file mode 100644 index 00000000..51502752 --- /dev/null +++ b/docs/administration.md @@ -0,0 +1,53 @@ +# Administration + +You can access uMap administration page by navigating to `https://your.server.org/admin` + +You will have to connect with the admin account created during installation. Default admin username is "umap". + +## Icons + +Icons (aka pictograms in uMap sources) can be used in your map markers. + +Icons are not embedded in uMap sources, you will have to add them manually. So you can choose which icons you want to use. + +Example of icons libraries you may want to use: + +- [Maki Icons](https://labs.mapbox.com/maki-icons/) (icon set made for map designers) +- [Osmic Icons](https://gitlab.com/gmgeo/osmic) +- [SJJB Icons](http://www.sjjb.co.uk/mapicons/contactsheet) + +### Import icons manually + +You can import icons manually by going to your uMap admin page: `https://your.server.org/admin` + +### Import icons automatically + +To import icons on your uMap server, you will need to use command `umap import_pictograms` + +Note, you can get help with `umap import_pictograms -h` + +In this example, we will import Maki icons. + +First, we download icons from main site. Inside the downloaded archive, we keep only the icons folder that contains svg files. Place this folder on your server. + +Go inside icons folder and remove tiny icons: `rm *-11.svg` + +Now, we will use imagemagick to convert svg to png. + +`for file in *.svg; do convert -background none $file ${file%15.svg}24.png; done` + +To have white icons use: +`for file in *.svg; do convert -background none -fuzz 100% -fill white -opaque black $file ${file%15.svg}24.png; done` + + +Notes: +- you may also want to resize image with option `-resize 24x` +- this solution is not optimal, generated png are blurry. + +This will convert the svg to png and rename them from `*-15.svg` to `*-24.png` + +Now we will import icons. Note: icons names must end with `-24.png` + +`umap import_pictograms --attribution "Maki Icons by Mapbox" icons` + +Done. Icons are imported. diff --git a/docs/contributing.md b/docs/contributing.md index 337ec1ea..f3ea73a8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -3,3 +3,94 @@ ## Translating Translation is managed through [Transifex](https://www.transifex.com/openstreetmap/umap/). + +## Bugs Triaging + +You are very welcome to help us triaging [uMap issues](https://github.com/umap-project/umap/issues). + +* Help other users by answering questions +* Give your point of view in discussions +* And so on... + +## Development on Ubuntu + +### Environnement setup + +Choose one of the following two config: + +#### Config global to your desktop + +Follow the procedure [Ubuntu from scratch](ubuntu.md) + +But instead using folders /etc/umap, you can create a ~/.umap folder. +This folder will contain the umap.conf file. + +And for folder /srv/umap, you can create a ~/umap folder (We will remove this folder later) + +You will have to set an env var, we will set it in your .bashrc: + + nano ~/.bashrc + +Add the following at the end of file: + +``` +# uMap +export UMAP_SETTINGS=~/.umap/umap.conf +``` + +Then refresh your terminal + + source ~/.bashrc + +Run your local uMap and check that it is working properly. + +#### Config inside your local git repo + +Follow the procedure [Ubuntu from scratch](ubuntu.md) + +You can use the local.py.sample in the git repo and copy it to your local git repo to umap/settings/local.py + +See [Installation](install.md) + +### Hacking on the code + +Create a workspace folder ~/wk and go into it. + +"git clone" the main repository and go in the umap folder + +Several commands, needs you to be in a virtualenv: + + virtualenv ~/wk/umap/venv --python=/usr/bin/python3.6 + source ~/wk/umap/venv/bin/activate + +Now, command "umap" will be available + +*Note: if you close your terminal, you will need to re-run command:* + + source /srv/umap/venv/bin/activate + +To test your code, you will add to install umap from your git folder. Go to ~/wk/umap and run: + + pip install -e . + # or pip install -e ~/wk/umap + +This command, will check dependencies and install uMap from sources inside folder. + +To start your local uMap: + + umap runserver 0.0.0.0:8000 + +### Update translations + +Install needed tools: + + apt install gettext transifex-client + +Pull the translations from transifex website: + + tx pull -f + +Then you will need to update binary files with command: + make compilemessages + +Done. You can now review and commit modified/added files. diff --git a/docs/install.md b/docs/install.md index 93c9ed90..9324ed1e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,5 +1,7 @@ # Installation +*Note: for Ubuntu follow procedure [Ubuntu from scratch](ubuntu.md)* + Create a geo aware database. See [Geodjango doc](https://docs.djangoproject.com/en/dev/ref/contrib/gis/install/) for backend installation. Create a virtual environment diff --git a/docs/ubuntu.md b/docs/ubuntu.md index 48072b0d..fabd9cc7 100644 --- a/docs/ubuntu.md +++ b/docs/ubuntu.md @@ -6,8 +6,9 @@ You need sudo grants on this server, and it must be connected to Internet. ## Install system dependencies - sudo apt install build-essential autoconf python3.5 python3.5-dev python-virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql-9.5 postgresql-server-dev-9.5 postgresql-9.5-postgis-2.2 git libxml2-dev libxslt1-dev zlib1g-dev + sudo apt install build-essential autoconf python3.6 python3.6-dev python-virtualenv wget nginx uwsgi uwsgi-plugin-python3 postgresql-9.5 postgresql-server-dev-9.5 postgresql-9.5-postgis-2.2 git libxml2-dev libxslt1-dev zlib1g-dev +*Note: nginx and uwsgi are not required for local development environment* *Note: uMap also works with python 2.7 and 3.4, so adapt the package names if you work with another version.* @@ -58,7 +59,7 @@ From now on, unless we say differently, the commands are run as `umap` user. ## Create a virtualenv and activate it - virtualenv /srv/umap/venv --python=/usr/bin/python3.5 + virtualenv /srv/umap/venv --python=/usr/bin/python3.6 source /srv/umap/venv/bin/activate *Note: this activation is not persistent, so if you open a new terminal window, @@ -74,6 +75,16 @@ you will need to run again this last line.* wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O /etc/umap/umap.conf +## Customize umap.conf + + nano /etc/umap/umap.conf + +Change the following properties: + +``` +STATIC_ROOT = '/srv/umap/var/static' +MEDIA_ROOT = '/srv/umap/var/data' +``` ## Create the tables diff --git a/mkdocs.yml b/mkdocs.yml index ddfe693c..be79a976 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,7 @@ site_name: uMap pages: - Home: index.md - Installation: install.md +- Administration: administration.md - Contributing: contributing.md - how-tos: - Ubuntu from scratch: ubuntu.md