From bba5cda46bd13bb06f0f4d0566245d0c755b14ee Mon Sep 17 00:00:00 2001 From: brentfraser Date: Sun, 26 Apr 2020 09:34:04 -0600 Subject: [PATCH 1/4] add Windows install info --- docs/index.md | 2 +- docs/install.md | 8 ++- docs/install_windows.md | 137 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 143 insertions(+), 4 deletions(-) create mode 100644 docs/install_windows.md diff --git a/docs/index.md b/docs/index.md index b536ccf7..48b53902 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# uMap developper documentation +# uMap developer documentation *This documentation is intended for people aiming to install and configure uMap. If you are looking for user documentation, have a look at [the OSM wiki page](http://wiki.openstreetmap.org/wiki/UMap#Tutorials).* diff --git a/docs/install.md b/docs/install.md index b8d7fe54..741899f1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -2,6 +2,8 @@ *Note: for Ubuntu follow procedure [Ubuntu from scratch](ubuntu.md)* +*Note: for a Windows installation follow procedure [Installing on Windows](install_windows.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 @@ -23,7 +25,7 @@ Reference it as env var: export UMAP_SETTINGS=`pwd`/local.py -Add database connexion informations in `local.py`, for example +Add database connection information in `local.py`, for example DATABASES = { 'default': { @@ -77,7 +79,7 @@ Start the server ## Search -UMap uses Postgresql tsvector for searching. In case your database is big, you +UMap uses PostgreSQL tsvector for searching. In case your database is big, you may want to add an index. For that, you should do so: CREATE EXTENSION unaccent; @@ -89,6 +91,6 @@ may want to add an index. For that, you should do so: ## Optimisations -To speed up uMap homepage rendering on a large instance, the following index can be added too (make sure you set the center to your default instance map center): +To speed up uMap homepage rendering on a large instance, the following index can be added tas well (make sure you set the center to your default instance map center): CREATE INDEX leaflet_storage_map_optim ON leaflet_storage_map (modified_at) WHERE ("leaflet_storage_map"."share_status" = 1 AND ST_Distance("leaflet_storage_map"."center", ST_GeomFromEWKT('SRID=4326;POINT(2 51)')) > 1000.0); diff --git a/docs/install_windows.md b/docs/install_windows.md new file mode 100644 index 00000000..54f6f237 --- /dev/null +++ b/docs/install_windows.md @@ -0,0 +1,137 @@ +# Installing uMap on Windows + +The **good news** is that it is possible to run uMap server on Windows. However, it is recommended using uMap on a +Linux distribution as it will be easier to install, modify, and deploy. While the following steps have been tested on +Windows 7, they may work for other versions of Windows. + + +## 1. Prepare the Database + +This assumes you've installed PostgreSQL. +- Create a database called "umap" +- Install PostGIS extension in it + +##2. Create a directory and a Python virtual environment + +Open a Windows command window, and cd to a directory of your choice. You need to create a sub-directory but the name is +up to you (it doesn't need to be called "production"): +``` +mkdir production +cd production +virtualenv venv +venv\Scripts\activate.bat +``` + +##3. Install GDAL for Python + +It is really difficult to install GDAL the "standard" way since it requires compiling GDAL. Instead download an already +compiled pip-compatible wheel package file from +[Unofficial Windows Binaries for Python Extension Packages](https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal). Note +that cp38 refers to the Python version you are using, so make sure you select the one that matches your Python version +for download. + +In the command window, install the downloaded wheel package: +`pip install GDAL-3.0.4-cp38-cp38-win_amd64.whl` + +You can test the install from the Python command line. From the Windows command window invoke Python: +``` +python +``` +then enter some Python commands: +```python +>>> import gdal +>>> print(int(gdal.VersionInfo('VERSION_NUM'))) +>>> exit() +``` + +##4. Install uMap + +In the Windows command window: +``` +mkdir static +mkdir data +pip install umap-project +``` +***Windows Work-Around 1*** + +Setting the UMAP_SETTINGS environment variable doesn't seem to work on Windows, so put the file in umap's fall-back +location of \etc\umap\umap.conf : +``` +mkdir \etc\umap +wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O \etc\umap\umap.conf +``` +Edit the umap.conf file: + +***Windows Work-Around 2*** + +It might be possible to modify django's libgdal.py (umap installed django as one of its dependencies) to detect the +installed GDAL, but until then you can explicitly state the required paths. + +Add the GDAL paths somewhere near the top of the umap.conf file (make sure the last part, "gdal300", is the name of the +GDAL DLL in its package dir): +```python +GDAL_LIBRARY_PATH = r'C:\temp\production\venv\Lib\site-packages\osgeo\gdal300' +GEOS_LIBRARY_PATH = r'C:\temp\production\venv\Lib\site-packages\osgeo\geos_c' +PROJ_LIB = r'C:\temp\production\venv\Lib\site-packages\osgeo\data\proj' +``` +And while you're editing umap.conf, add the needed parameters to the DATABASES default object : +```python +DATABASES = { + 'default': { + 'ENGINE': 'django.contrib.gis.db.backends.postgis', + 'NAME': 'umap', + 'USER': 'postgres', + 'PASSWORD': 'postgres', + 'HOST': 'localhost', + 'PORT': '5432' + } +} +``` +And set umap's paths to where you've created the directories: +```python +STATIC_ROOT = '/temp/production/static' +MEDIA_ROOT = '/temp/production/data' +``` +Now that the minimal configuration is done, you can do the django-ish portion of the umap install. In the Windows +command window: +``` +umap migrate +umap collectstatic +umap createsuperuser +``` + +***Windows Work-Around 3*** + +Strangely, having the installed `umap.exe` is not enough. Some script tries to execute "umap" without the ".exe" +extension, so here's a hack to make that work: +``` +copy venv\scripts\umap.exe venv\scripts\umap +``` + +##5. Run umap server +In the Windows command window: +``` +umap runserver 127.0.0.1:8000 +``` +You should now be able to open a browser and go to http://127.0.0.1:8000 + +If you add some features to a new map and try to save them, you will likely see an error in the Windows command window +running the umap server. This error is a Python error related to doing +`os.remove(name)` on Windows: +``` + File "c:\temp\test\venv\lib\site-packages\django\core\files\storage.py", line 303, in delete + os.remove(name) +PermissionError: [WinError 32] The process cannot access the file because it is being used by another process: +'C:\\temp\\production\\data\\datalayer\\1\\1\\layer-1.geojson' +``` + +***Windows Work-Around 4*** + +Edit `test\venv\lib\site-packages\django\core\files\storage.py`, and comment out lines 302 and 303: +```python +# else: +# os.remove(name) +``` +Now adding features and saving should work. _Now here's the weird part._ Edit `storage.py` to restore it to it's +original state by removing the comment characters you put in. Save the changes, do some more feature editing and +saving in your browser. It still works! This may be due to file/directory locking by Windows. From c5cd0e1c38235b065604c665ead3b29bab776ec3 Mon Sep 17 00:00:00 2001 From: brentfraser Date: Sun, 26 Apr 2020 09:37:04 -0600 Subject: [PATCH 2/4] typo --- docs/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.md b/docs/install.md index 741899f1..2d4961a9 100644 --- a/docs/install.md +++ b/docs/install.md @@ -91,6 +91,6 @@ may want to add an index. For that, you should do so: ## Optimisations -To speed up uMap homepage rendering on a large instance, the following index can be added tas well (make sure you set the center to your default instance map center): +To speed up uMap homepage rendering on a large instance, the following index can be added as well (make sure you set the center to your default instance map center): CREATE INDEX leaflet_storage_map_optim ON leaflet_storage_map (modified_at) WHERE ("leaflet_storage_map"."share_status" = 1 AND ST_Distance("leaflet_storage_map"."center", ST_GeomFromEWKT('SRID=4326;POINT(2 51)')) > 1000.0); From 7e952b0dea450ac35cf2c6eb788e07ba5a543017 Mon Sep 17 00:00:00 2001 From: brentfraser Date: Sun, 26 Apr 2020 09:46:28 -0600 Subject: [PATCH 3/4] typos --- docs/contributing.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index f3ea73a8..2f78c549 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,7 +4,7 @@ Translation is managed through [Transifex](https://www.transifex.com/openstreetmap/umap/). -## Bugs Triaging +## Bug Triaging You are very welcome to help us triaging [uMap issues](https://github.com/umap-project/umap/issues). @@ -14,7 +14,7 @@ You are very welcome to help us triaging [uMap issues](https://github.com/umap-p ## Development on Ubuntu -### Environnement setup +### Environment setup Choose one of the following two config: @@ -58,7 +58,7 @@ 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: +Several commands you need to issue to be in a virtualenv: virtualenv ~/wk/umap/venv --python=/usr/bin/python3.6 source ~/wk/umap/venv/bin/activate @@ -74,7 +74,7 @@ To test your code, you will add to install umap from your git folder. Go to ~/wk pip install -e . # or pip install -e ~/wk/umap -This command, will check dependencies and install uMap from sources inside folder. +This command will check dependencies and install uMap from sources inside folder. To start your local uMap: @@ -91,6 +91,7 @@ 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. From a7241d6459c247abf29fb6c5cc66595cc6f391e4 Mon Sep 17 00:00:00 2001 From: brentfraser Date: Tue, 28 Apr 2020 11:28:48 -0600 Subject: [PATCH 4/4] add note on developing --- docs/install_windows.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/install_windows.md b/docs/install_windows.md index 54f6f237..5ae27a1b 100644 --- a/docs/install_windows.md +++ b/docs/install_windows.md @@ -13,6 +13,8 @@ This assumes you've installed PostgreSQL. ##2. Create a directory and a Python virtual environment +This assumes you've installed Python (version 3.8+ 64-bit is a good choice) and virtualenv. + Open a Windows command window, and cd to a directory of your choice. You need to create a sub-directory but the name is up to you (it doesn't need to be called "production"): ``` @@ -135,3 +137,8 @@ Edit `test\venv\lib\site-packages\django\core\files\storage.py`, and comment out Now adding features and saving should work. _Now here's the weird part._ Edit `storage.py` to restore it to it's original state by removing the comment characters you put in. Save the changes, do some more feature editing and saving in your browser. It still works! This may be due to file/directory locking by Windows. + +##6. Installing for development + +The previous sections describe the install procedure for running the released version of uMap "as-is". If you want to +modify uMap (and possibly contribute your changes back to the uMap team), have a look at [Contributing](contributing.md) \ No newline at end of file