diff --git a/README.md b/README.md index 184a8f6b..ed46bc02 100644 --- a/README.md +++ b/README.md @@ -11,105 +11,6 @@ uMap lets you create maps with OpenStreetMap layers in a minute and embed them i It uses [django-leaflet-storage](https://github.com/umap-project/django-leaflet-storage) and [Leaflet.Storage](https://github.com/umap-project/Leaflet.Storage), built on top of Django and Leaflet. -## Quickstart +## Installation and configuration -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 - - virtualenv umap - source umap/bin/activate - -Install dependencies and project - - cd YOUR_SOURCE_DIR - git clone git@github.com:umap-project/umap.git - cd umap - pip install -r requirements.txt - pip install -e . - -Create a default local settings file - - cp umap/settings/local.py.sample umap/settings/local.py - -Add database connexion informations in `local.py`, for example - - DATABASES = { - 'default': { - 'ENGINE': 'django.contrib.gis.db.backends.postgis', - 'NAME': 'umap', - } - } - -Add a `SECRET_KEY` in `local.py` with a long random secret key - - SECRET_KEY = "a long and random secret key that must not be shared" - -uMap uses [django-social-auth](http://django-social-auth.readthedocs.org/) for user authentication. So you will need to configure it according to your -needs. For example - - AUTHENTICATION_BACKENDS = ( - 'social_auth.backends.contrib.github.GithubBackend', - 'social_auth.backends.contrib.bitbucket.BitbucketBackend', - 'social_auth.backends.twitter.TwitterBackend', - 'django.contrib.auth.backends.ModelBackend', - ) - GITHUB_APP_ID = 'xxx' - GITHUB_API_SECRET = 'zzz' - BITBUCKET_CONSUMER_KEY = 'xxx' - BITBUCKET_CONSUMER_SECRET = 'zzz' - TWITTER_CONSUMER_KEY = "xxx" - TWITTER_CONSUMER_SECRET = "yyy" - -Example of callback URL to use for setting up OAuth apps - - http://umap.foo.bar/complete/github/ - -Adapt the `STATIC_ROOT` and `MEDIA_ROOT` to your local environment. - -Create the tables - - python manage.py migrate - -Collect and compress the statics - - python manage.py collectstatic - python manage.py compress - -Create a superuser - - python manage.py createsuperuser - -Add a site object - - python manage.py shell - from django.contrib.sites.models import Site - Site.objects.create(name='example.com', domain='example.com') - -Start the server - - python manage.py runserver 0.0.0.0:8000 - -Go to the admin (http://localhost:8000/admin/) and add: - -- at least one license -- at least one tile layer - -## Search - -UMap uses Postgresql tsvector for searching. It case your database is big, you -may want to add an index. For that, you sould do so: - - CREATE EXTENSION unaccent; - CREATE EXTENSION btree_gin; - ALTER FUNCTION unaccent(text) IMMUTABLE; - ALTER FUNCTION to_tsvector(text) IMMUTABLE; - CREATE INDEX search_idx ON leaflet_storage_map USING gin(to_tsvector(unaccent(name)), share_status); - -To speep up umap home page rendering on large instance, the following index can be added too (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); - -## Translating - -Everything is managed through Transifex: https://www.transifex.com/projects/p/umap/ +See [developper documentation](https://umap.readthedocs.org/install/). diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..615fe0f6 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,5 @@ +# Contributing + +## Translating + +Translation is managed through [Transifex](https://www.transifex.com/yohanboniface/umap/dashboard/). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..b536ccf7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# uMap developper 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).* + +uMap is a Django project, so in case of doubt always refer to the [Django documentation](https://docs.djangoproject.com). + +Now let's start by [installing uMap](install.md)! diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..3f2cff48 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,97 @@ +# Installation + +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 + + virtualenv umap + source umap/bin/activate + +Install dependencies and project + + pip install umap + +Create a default local settings file + + wget https://raw.githubusercontent.com/umap-project/umap/master/umap/settings/local.py.sample -O local.py + + +Reference it as env var: + + export UMAP_SETTINGS=`pwd`/local.py + + +Add database connexion informations in `local.py`, for example + + DATABASES = { + 'default': { + 'ENGINE': 'django.contrib.gis.db.backends.postgis', + 'NAME': 'umap', + } + } + +Add a `SECRET_KEY` in `local.py` with a long random secret key + + SECRET_KEY = "a long and random secret key that must not be shared" + +uMap uses [python-social-auth](http://python-social-auth.readthedocs.org/) for user authentication. So you will need to configure it according to your +needs. For example + + AUTHENTICATION_BACKENDS = ( + 'social_auth.backends.contrib.github.GithubBackend', + 'social_auth.backends.contrib.bitbucket.BitbucketBackend', + 'social_auth.backends.twitter.TwitterBackend', + 'django.contrib.auth.backends.ModelBackend', + ) + GITHUB_APP_ID = 'xxx' + GITHUB_API_SECRET = 'zzz' + BITBUCKET_CONSUMER_KEY = 'xxx' + BITBUCKET_CONSUMER_SECRET = 'zzz' + TWITTER_CONSUMER_KEY = "xxx" + TWITTER_CONSUMER_SECRET = "yyy" + +Example of callback URL to use for setting up OAuth apps + + http://umap.foo.bar/complete/github/ + +Adapt the `STATIC_ROOT` and `MEDIA_ROOT` to your local environment. + +Create the tables + + umap migrate + +Collect and compress the statics + + umap collectstatic + umap compress + +Create a superuser + + umap createsuperuser + +Start the server + + umap runserver 0.0.0.0:8000 + +Go to the admin (http://localhost:8000/admin/) and add: + +- at least one license +- at least one tile layer + +## Search + +UMap uses Postgresql tsvector for searching. It case your database is big, you +may want to add an index. For that, you sould do so: + + CREATE EXTENSION unaccent; + CREATE EXTENSION btree_gin; + ALTER FUNCTION unaccent(text) IMMUTABLE; + ALTER FUNCTION to_tsvector(text) IMMUTABLE; + CREATE INDEX search_idx ON leaflet_storage_map USING gin(to_tsvector(unaccent(name)), share_status); + + +## Optimisations + +To speep up umap home page rendering on large instance, the following index can be added too (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/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..b98b75b2 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,6 @@ +site_name: uMap +pages: +- Home: index.md +- Installation: install.md +- Contributing: contributing.md +theme: readthedocs diff --git a/requirements-dev.txt b/requirements-dev.txt index 125b4602..86559899 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,2 +1,3 @@ pytest pytest-django +mkdocs