Skip to content
Browse files

New version of the docs

  • Loading branch information...
1 parent 51ed575 commit 21fdae9c7fb23dfcfdaeff733a364b61352a794d @ingenieroariel ingenieroariel committed
Showing with 2,471 additions and 1,210 deletions.
  1. +57 −16 docs/Makefile
  2. +88 −26 docs/{source → }/conf.py
  3. +50 −0 docs/deploy/customize.txt
  4. +36 −0 docs/deploy/debug.txt
  5. 0 docs/{source/deploy → deploy/images}/GeoServer-JAI-Settings.png
  6. 0 docs/{source/deploy → deploy/images}/GeoServer-Web-Map-Service.png
  7. +176 −2 docs/{source/deploy/tarball.rst → deploy/install.txt}
  8. +136 −23 docs/{source/deploy/production.rst → deploy/production.txt}
  9. +294 −0 docs/developers/architecture.txt
  10. +52 −0 docs/developers/contribute.txt
  11. +210 −0 docs/developers/extend.txt
  12. +78 −0 docs/developers/gnips.txt
  13. +57 −0 docs/developers/patches.txt
  14. +80 −0 docs/{source/django-apps/maps.rst → developers/reference/django-apps.txt}
  15. +1 −41 docs/{source/geoserver-extensions.rst → developers/reference/geoserver.txt}
  16. +12 −0 docs/developers/reference/index.txt
  17. +1 −0 docs/{source/geonode-javascript.rst → developers/reference/javascript.txt}
  18. +47 −0 docs/developers/roadmap.txt
  19. +228 −0 docs/developers/setup.txt
  20. +65 −42 docs/{source/developers/integration-testing.rst → developers/tests.txt}
  21. +85 −0 docs/index.txt
  22. +53 −0 docs/intro/install.txt
  23. +61 −0 docs/intro/overview.txt
  24. +72 −15 docs/make.bat
  25. +0 −11 docs/source/about-geonode.rst
  26. +0 −417 docs/source/deploy/centos.rst
  27. +0 −39 docs/source/deploy/ubuntu.rst
  28. +0 −218 docs/source/deployment.rst
  29. +0 −26 docs/source/django-apps.rst
  30. +0 −28 docs/source/django-apps/core.rst
  31. +0 −20 docs/source/django-apps/proxy.rst
  32. +0 −6 docs/source/geonetwork-extensions.rst
  33. +0 −194 docs/source/getting-started.rst
  34. +0 −32 docs/source/index.rst
  35. +0 −54 docs/source/logging.rst
  36. +89 −0 docs/users/create.txt
  37. +103 −0 docs/users/explore.txt
  38. BIN docs/users/images/activation_email.png
  39. BIN docs/users/images/activation_sent.png
  40. BIN docs/users/images/logged_in.png
  41. BIN docs/users/images/login_form.png
  42. BIN docs/users/images/login_register.png
  43. BIN docs/users/images/register_form.png
  44. +32 −0 docs/users/index.txt
  45. +55 −0 docs/users/register.txt
  46. +95 −0 docs/users/share.txt
  47. +158 −0 docs/users/upload.txt
View
73 docs/Makefile
@@ -10,22 +10,28 @@ BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " dirhtml to make HTML files named index.html in directories"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
@@ -40,6 +46,11 @@ dirhtml:
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@@ -61,16 +72,46 @@ qthelp:
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
- @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GeoNodeDeveloperDocumentation.qhcp"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GeoNode.qhcp"
@echo "To view the help file:"
- @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GeoNodeDeveloperDocumentation.qhc"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GeoNode.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/GeoNode"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GeoNode"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
- @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
- "run these through (pdf)latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
View
114 docs/source/conf.py → docs/conf.py
@@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
#
-# GeoNode Developer Documentation documentation build configuration file, created by
-# sphinx-quickstart on Wed May 12 15:50:17 2010.
+# GeoNode documentation build configuration file, created by
+# sphinx-quickstart on Mon Oct 3 16:20:38 2011.
#
# This file is execfile()d with the current directory set to its containing dir.
#
@@ -16,10 +16,13 @@
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = []
@@ -28,26 +31,26 @@
templates_path = ['_templates']
# The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = '.txt'
# The encoding of source files.
-#source_encoding = 'utf-8'
+#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
-project = u'GeoNode Developer Documentation'
-copyright = u'2010, David Winslow'
+project = u'GeoNode'
+copyright = u'2011, GeoNode development team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '0.1'
+version = '1.1'
# The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '1.1RC2'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -59,12 +62,9 @@
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = []
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
@@ -89,9 +89,9 @@
# -- Options for HTML output ---------------------------------------------------
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme = 'default'
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'nature'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -120,7 +120,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
@@ -138,7 +138,7 @@
#html_additional_pages = {}
# If false, no module index is generated.
-#html_use_modindex = True
+#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
@@ -149,16 +149,22 @@
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
# Output file base name for HTML help builder.
-htmlhelp_basename = 'GeoNodeDeveloperDocumentationdoc'
+htmlhelp_basename = 'GeoNodedoc'
# -- Options for LaTeX output --------------------------------------------------
@@ -172,8 +178,8 @@
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('index', 'GeoNodeDeveloperDocumentation.tex', u'GeoNode Developer Documentation Documentation',
- u'David Winslow', 'manual'),
+ ('index', 'GeoNode.tex', u'GeoNode Documentation',
+ u'GeoNode development team', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -184,6 +190,12 @@
# not chapters.
#latex_use_parts = False
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
@@ -191,4 +203,54 @@
#latex_appendices = []
# If false, no module index is generated.
-#latex_use_modindex = True
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'geonode', u'GeoNode Documentation',
+ [u'GeoNode development team'], 1)
+]
+
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'GeoNode'
+epub_author = u'GeoNode development team'
+epub_publisher = u'GeoNode development team'
+epub_copyright = u'2011, GeoNode development team'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
View
50 docs/deploy/customize.txt
@@ -0,0 +1,50 @@
+========================================
+Customizing the look and feel of GeoNode
+========================================
+
+This section will explain how to change GeoNode's main logo, the index page and the colors.
+It also contains an introduction to Django's template and media management.
+
+The paths to the different locations are assumed to be on Ubuntu with GeoNode installed via packages, but the same notions can be applied in any deployment.
+
+Customizing the home page
+=========================
+
+GeoNode uses Django's template engine, :file:`/etc/geonode/templates` is empty by default but it is abover other folders in the template lookup hierarchy.
+This means that it is possible to copy any html template to that location and it will take precence.
+Let's start by doing the following::
+
+ sudo cp /var/lib/geonode/src/GeoNodePy/geonode/templates/index.html /etc/geonode/templates
+
+The copy of :file:`index.html` that was just created takes precedence over the default one, the text in the main section can be changed there and a reload of the web page in the browser will show the updated version.
+
+.. note:: Changes to templates are picked up automatically and do not require a server restart.
+
+With the same approach, the structure of all pages can be modified by copying and then editing ``page_template.html``. We recommend reading about the `Django template language`_ for advanced customizations.
+
+.. _ Django template language: http://docs.djangoproject.com/
+
+.. note:: While editing the templates in place will also achieve the expected results, it will make upgrading GeoNode harder, therefore it is recommended to follow the approach described above.
+
+
+Changing the default logo
+=========================
+
+Similarly to the way the templates work, GeoNode's images and css files can be overriden in :file:`/etc/geonode/media`.
+
+The original GeoNode logo is located at :file:`/var/lib/geonode/src/GeoNode/geonode/media/theme/img/logo-bg.png`.
+Make a copy and edit it using Photoshop, GIMP, or your preferred image editor and then save it in :file:`/etc/geonode/media/theme/img/logo-bg.png`.
+
+Once the logo is placed there, it is neccessary to run the media collection command::
+
+ sudo geonode collectstatic -v0
+
+This will gather all the media in the diferent locations (both source and the user customizations) and put it in the directory being served by apache: :file:`/var/www/geonode/static/`.
+
+.. note:: It is not recommended to change the files directly in :file:`/var/www/geonode/static/` because they are overwritten any time the media collaction command is run.
+
+
+Changing the entire site media
+==============================
+
+All the files in :file:`/var/lib/geonode/src/GeoNodePy/geonode/media/theme` can be overriden using this method, including :file:`css/base.css` which contains most of the color schemes for the entire site.
View
36 docs/deploy/debug.txt
@@ -0,0 +1,36 @@
+===============================
+Debugging GeoNode installations
+===============================
+
+There are several mechanisms to debug GeoNode installations, the most common ones are discussed in the following sections.
+
+Viewing the logs
+================
+
+There are many kinds of logs in GeoNode, most of them are located in :file:`/var/log/geonode/` and will be explained below in order of relevance:
+
+ * **GeoNode main log**: This is the output of the Django aplication coming from Apache, it may contain detailed information about uploads and high level problems.
+ The default location is :file:`/var/log/geonode/apache.log` or :file:`/var/log/apache2/error.log`.
+ It is set to a very low level by default, but it's output can be increased by setting the logging level to ``DEBUG`` in :file:/etc/geonode/local_settings.py.
+
+ * **GeoServer log**: It contains most of the information related to problems with data, rendering and styling errors.
+ This one can be accessed at ``GEOSERVER_DATA_DIR/logs/geoserver.log``, which is usually :file:`/var/lib/geoserver/geonode-data/logs/geoserver.log``.
+ It may also be symlinked in :file:`/var/log/geonode/geoserver.log`.
+
+ * **Geonetwork log**: Contains information about CSW and metadata handling.
+ Records related to bad html parsing could be further identified by analyzing GeoNetwork logs.
+ It is symlinked in :file:`/var/log/geonode/geonetwork.log` and originally in :file:`/var/lib/tomcat6/logs/geonetwork.log`.
+
+ * **Tomcat logs**: Tomcat logs could indicate problems loading GeoServer or GeoNetwork.
+ They can be found at :file:`/var/lib/tomcat6/logs/catalina.out`.
+
+ * **PostgreSQL logs**: Postgres is accessed by GeoNetwork, GeoServer and Django, therefore, very hard to debug errors could be found by looking at PostgreSQL's logs.
+ They are located at :file:`/var/log/postgresql/postgresql-8.4-main.log`.
+
+
+Enabling DEBUG mode
+===================
+
+Django can be set to return pretty formatted exceptions instead of ``500 errors``.
+This can be set by setting ``DEBUG=True`` in :file:`/etc/geonode/local_settings.py`.
+
View
0 .../source/deploy/GeoServer-JAI-Settings.png → .../deploy/images/GeoServer-JAI-Settings.png
File renamed without changes
View
0 ...urce/deploy/GeoServer-Web-Map-Service.png → ...ploy/images/GeoServer-Web-Map-Service.png
File renamed without changes
View
178 docs/source/deploy/tarball.rst → docs/deploy/install.txt
@@ -1,10 +1,33 @@
-Deploying from the GeoNode tar.gz Distribution
-==============================================
+==========================
+General installation guide
+==========================
+
+.. note:: The quick installation guide contains instructions to set it up in most common platforms. It can be found :doc:`here </intro/install>`.
+
+This page describes a generic installation process for GeoNode systems.
+For some platforms the GeoNode project also provides customized installers which are easier to use and more reliable.
The most generic package provided by the GeoNode project is the tar.gz ("tarball").
This is the most customizable, but also the most difficult, installation mechanism for GeoNode.
Some platforms have more convenient packages available, so check at :doc:`/deployment` to see whether one is available for your OS before going through these steps.
+
+Recommended Minimum System Requirements
+=======================================
+
+For deployment of GeoNode on a single server, the following are the bare minimum system requirements:
+
+* 6GB of RAM, including swap space.
+* 2.2GHz processor. (Additional processing power may be required for multiple concurrent styling renderings)
+* 1 GB software disk usage.
+* Additional disk space for any data hosted with GeoNode and tiles cached with GeoWebCache.
+ For spatial data, cached tiles, and "scratch space" useful for administration, a decent baseline size for GeoNode deployments is 100GB.
+* 64-bit hardware recommended.
+
+
+Installing GeoNode from a release
+=================================
+
What's in the Package?
----------------------
@@ -29,6 +52,7 @@ The stack used is:
* *Django Database*: PostgresQL
+
Download GeoNode Release Archive
--------------------------------
You get the latest GeoNode release from http://dev.geonode.org/release/ or the `GeoNode project wiki <http://dev.geonode.org/trac/>`_ .
@@ -46,6 +70,7 @@ You can unpack it like::
This tarball comes with an install script and a directory with supporting config files.
+
Installing Dependencies
-----------------------
@@ -78,6 +103,7 @@ Ubuntu
postgresql-8.4-postgis,libpq-dev unzip libjpeg-dev libpng-dev
python-gdal \ libproj-dev python-psycopg2 apache2 libapache2-mod-wsgi
+
Installation
------------
@@ -94,11 +120,15 @@ Installation
$ cd GeoNode-1.1/
$ sudo ./install.sh support/config-ubuntu.sh
+
Manual Installation
===================
+
This section is mostly intended for packagers working on installers for GeoNode on new platforms.
If you simply want a customized installation of GeoNode, we recommend reviewing and modifying the installer script included with GeoNode instead of starting "from scratch."
+A GeoNode installation has two webservers running alongside, one for the Java applications and another one for the Python/Django applications and static files.
+
The key points of setting up a GeoNode installation are as follows:
1) *Set up applications.*
@@ -128,3 +158,147 @@ The key points of setting up a GeoNode installation are as follows:
* ``GEONETWORK_BASE_URL`` the base URL for the GeoNetwork for your GeoNode site, for example `http:/example.com/geonetwork/`.
* ``GEONODE_CLIENT_LOCATION`` the URL where the static files for GeoNode are published, for example `http://example.com/media/`. These files can be found on disk in the directory where you installed the Django application under :file:src/GeoNodePy/geonode/media/ .
+
+
+Java Web Applications (WARs)
+============================
+
+GeoNode requires a Java servlet container compatible with the J2EE standard,
+2.5 or higher. `Jetty <http://jetty.mortbay.org/>`_ and `Tomcat
+<http://tomcat.apache.org/>`_ are two good free servlet containers. See their
+web sites for installation and application deployment instructions.
+
+
+GeoNetwork with GeoNode Schema
+------------------------------
+
+GeoNode's GeoNetwork integration requires use of a customized metadata schema.
+The GeoNode project provides a custom build of GeoNetwork with this extra
+schema pre-installed. This GeoNetwork is ready to run out-of-the-box; simply
+deploy using your servlet container's usual mechanism.
+
+Steps
+~~~~~
+
+1. *Deploy* GeoNetwork to your servlet container using the normal mechanism.
+ For Tomcat and Jetty, this simply means placing ``geonetwork.war`` in the
+ webapps subdirectory of the servlet container's installation directory.
+
+2. *Configure* GeoNetwork by changing the administrative account password
+ through GeoNetwork's web interface. The administrative account username and
+ password are both ``admin`` by default.
+
+3. *Remove* the sample metadata records that are included with GeoNetwork by
+ default. To do so, you can simply perform a search with no terms, then use
+ the 'Select all' link on the search results page to select all records in
+ the GeoNetwork site. Finally, use the 'actions on selection' menu to delete
+ the records.
+
+.. note::
+
+ GeoNode releases do not include the Intermap service that normally
+ accompanies GeoNetwork installations. As a result, some JavaScript errors
+ come up while performing searches. These are not a problem.
+
+
+GeoServer with GeoNode Extensions
+---------------------------------
+
+GeoNode's GeoServer integration requires some specific extensions to help
+GeoNode in managing GeoServer layers. GeoNode releases include a GeoServer WAR
+archive with these extensions pre-installed. However, some manual
+configuration may still be needed.
+
+Steps
+~~~~~
+
+1. *Deploy* GeoServer to your servlet container using the normal mechanism.
+ For Tomcat and Jetty, this simply means placing
+ ``geoserver-geonode-dev.war`` in the webapps subdirectory of the servlet
+ container's installation directory.
+
+2. *Configure* GeoServer with the location of the GeoNode site, used for
+ authentication (so that GeoServer can recognize logins from the main site).
+ This setting defaults to http://localhost:8000/, so if you are running
+ the GeoNode Django application on a different port, or on a different server
+ from the one running GeoServer, then you will need to change this by adding
+ a block of XML to ``WEB-INF/web.xml`` within the unpacked application
+ directory, like so::
+
+ <context-param>
+ <param-name>GEONODE_BASE_URL</param-name>
+ <param-value>http://localhost:8080/</param-value>
+ </context-param>
+
+ The ``<param-value>`` tag should enclose the URL to the Django application
+ homepage.
+
+
+Static Resources
+----------------
+
+The GeoNode project provides an archive of the minified JavaScript and CSS
+resources used in the GeoNode site. These media can simply be served with a
+static file server such as Apache httpd or lighttpd. See
+http://httpd.apache.org/docs/2.2/urlmapping.html and
+http://redmine.lighttpd.net/projects/lighttpd/wiki/Server.document-rootDetails
+for information on configuring Apache httpd and lighttpd to serve files,
+respectively. Many other web servers are perfectly capable of serving these
+files; Apache httpd and lighttpd are just examples.
+
+Steps:
+~~~~~~
+
+1. *Configure* a document root in your webserver, pointing to some directory on
+ your filesystem.
+
+2. *Extract* all the JavaScript and CSS files from the GeoNode release archive
+ (geonode-client.zip) into the document root.
+
+
+Django Web Application
+----------------------
+
+The GeoNode Django application should run in mod_wsgi under Apache httpd.
+See the Django project's deployment documentation for more information.
+However, we highly recommend using virtualenv to sandbox the GeoNode
+dependencies from the rest of the Python software on your system.
+
+Steps:
+~~~~~~
+
+1. *Install virtualenv* if you do not already have it available. It can easily
+ be installed via easy_install or pip::
+
+ $ easy_install virtualenv
+ $ pip install virualenv
+
+2. *Prepare a sandbox* for GeoNode using virtualenv::
+
+ $ virtualenv geonode
+ $ cd geonode
+ $ source bin/activate
+
+3. *Install* the geonode python modules from the Pip bundle::
+
+ $ pip install geonode-webapp.pybundle
+
+ If this step fails, make sure that you have a working C++ compiler installed
+ and development versions of the requisite libraries, listed in the GeoNode
+ README file.
+
+4. *Configure* the geonode Django app by editing
+ ``./src/GeoNodePy/geonode/settings.py``. The available settings and their
+ usage is described elsewhere in this documentation.
+
+5. If running via fastcgi, you can use the django-admin.py script to launch the
+ fastcgi server for Django. If running via WSGI, ensure that the virtualenv
+ is added to the python path for the WSGI script. See the official `Django
+ deployment documentation
+ <http://docs.djangoproject.com/en/1.2/howto/deployment/>`_ for details.
+
+
+Additional Configuration
+------------------------
+
+After installing, it is highly advised to follow the :doc:`post installation guide </deploy/production>`.
View
159 docs/source/deploy/production.rst → docs/deploy/production.txt
@@ -3,11 +3,12 @@ Configuring GeoNode for Production
==================================
This page documents recommendations for configuring GeoNode in production environments.
+The steps mentioned in the first section are required to run GeoNode, the ones in the second section are either optional or ways to get more performance.
Required steps
==============
-Create a super user
+Creating a super user
---------------------
To create a superuser you can run::
@@ -19,12 +20,21 @@ or, if you installed by source::
source path/to/geonode/virtualenv/bin/activate
django-admin.py createsuperuser --settings=geonode.settings
+Once your user is created, you can navigate to your site using the IP address and log in. But don't forget to change the SITEURL as explained in the next step before uploading data.
-Configure the correct DNS or IP address
+Configuring the correct DNS or IP address
-----------------------------------------
By default GeoNode runs in ``http://localhost/``, but when running in production in needs to know the public IP address or the DNS entry.
-To configure it, edit the ``SITEURL`` setting in ``local_settings.py`` (which can be found either in your GeoNodePy/src/geonode folder or in ``/etc/geonode/local_settings.py`` if you used an automated installer.
+To configure it, edit the ``SITEURL`` setting in ``local_settings.py`` (which can be found either in your GeoNodePy/src/geonode folder or in ``/etc/geonode/local_settings.py`` if you used an automated installer, for example::
+
+ SITEURL='http://127.0.0.1/'
+
+Once that it is changed you have to re-start the apache server::
+
+ sudo service apache2 restart
+
+.. warning:: Don't forget the trailing slash, because it is used to construct the ``GEOSERVER_BASE_URL`` param.
Set the correct GeoServer Proxy URL value
@@ -58,7 +68,7 @@ Get an API key from Microsoft at http://bingmapsportal.com/ and place it in ``lo
},{
"source": {
- "ptype":"gxp_bingsource",
+ "ptype":"gxp_bingsource",
"apiKey": "YOUR_BING_API"
},
"group":"background",
@@ -79,8 +89,8 @@ Copy the ``MAP_BASELAYERS`` dictionary from ``settings.py`` into ``local_setting
},{
"source": {
- "ptype":"gxp_googlesource",
- "apiKey": GOOGLE_API_KEY
+ "ptype":"gxp_googlesource",
+ "apiKey": GOOGLE_API_KEY
},
"group":"background",
"name":"SATELLITE",
@@ -88,6 +98,74 @@ Copy the ``MAP_BASELAYERS`` dictionary from ``settings.py`` into ``local_setting
"fixed": True,
+Sitemaps Configuration
+----------------------
+
+GeoNode can automatically generate a sitemap suitable for submission to search
+engines which can help them to index your GeoNode site more efficiently and
+effectively.
+
+In order to generate the sitemap properly, the sites domain name must be set
+within the sites framework. This requires that an admin user login to the
+admin interface and navigate to the sites module and change example.com to the
+actual domain name (and port if applicable). The admin interface can be accessed
+at http://<host>:<port>/admin/sites/site/
+
+It is possible to 'inform' google of changes to your sitemap. This is accomplished
+using the ping_google management command. More information can be found here
+http://docs.djangoproject.com/en/dev/ref/contrib/sitemaps/#django.contrib.sitemaps.ping_google
+It is recommended to put this call into a cron (scheduled) job to update google periodically.
+
+
+Configuring User Registration
+-----------------------------
+
+.. note:: This is done by default in the Ubuntu packages.
+
+You can optionally configure GeoNode to allow new users to register through the web. New registrants will be sent an email inviting them to activate their account.
+
+To allow new user registration:
+
+1. Set up the email backend for Django (see `Django documentation <http://docs.djangoproject.com/en/dev/topics/email/#e-mail-backends>`_) and add the appropriate settings to ``./src/GeoNodePy/geonode/settings.py``. For example::
+
+ EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
+ EMAIL_HOST = 'smtp.gmail.com'
+ EMAIL_HOST_USER = 'foo@gmail.com'
+ EMAIL_HOST_PASSWORD = 'bar'
+ EMAIL_PORT = 587
+ EMAIL_USE_TLS = True
+
+2. One week activation window::
+
+ ACCOUNT_ACTIVATION_DAYS = 7
+
+3. In the same settings file set::
+
+ REGISTRATION_OPEN=True
+
+4. With the Django application running, set the domain name of the service properly through the admin interface. (This domain name is used in the account activation emails.)::
+
+ http://localhost:8000/admin/sites/site/1
+
+To register as a new user, click the ''Register'' link in the GeoNode index header.
+
+Additional Configuration
+------------------------
+
+Some other things that require tweaking:
+
+* Web-accessible uploads directory for user profile photos
+
+* Configuring GeoNetwork/Django to use a "real" Postgres database instead of
+ embedded ones.
+
+* In order to generate the sitemap properly, the sites domain name must be set
+ within the sites framework. This requires that an admin user login to the
+ admin interface and navigate to the sites module and change example.com to the
+ actual domain name (and port if applicable). The admin interface can be accessed
+ at http://<host>:<port>/admin/sites/site/
+
+
Robot Exclusion File
--------------------
@@ -102,6 +180,7 @@ In order to request that "robots" do not make requests directly to GeoServer, yo
This will only affect automated web agents; web browsers in particular are unaffected.
+
Memory Management
-----------------
@@ -120,6 +199,7 @@ On Linux and MacOSX hosts, you can check the available RAM with the following co
The "total" column lists the available physical memory and swap space in megabytes; adding them together yields the amount of virtual memory available to the system.
In this example, there is no Swap space so that field is 0 and the available RAM on the system is 6096MB (6 GB).
+
Configuring the Servlet Container
---------------------------------
@@ -127,6 +207,7 @@ GeoServer is the most resource intensive component of GeoNode.
There are some general notes on setting up GeoServer for production environments in the `GeoServer manual <http://docs.geoserver.org/stable/en/user/production/index.html>`_ .
However, the following are some GeoServer recommendations with GeoNode's specific needs in mind.
+
JVM Options
-----------
@@ -140,6 +221,7 @@ Startup options should include the following::
These can be specified using the ``CATALINA_OPTS`` variable in Tomcat's ``bin/catalina.sh`` file, or the ``JETTY_OPTS`` in Jetty's ``bin/jetty.sh`` file.
+
Constrain GeoServer Worker Threads
----------------------------------
@@ -162,19 +244,22 @@ Add a ``maxThreads`` attribute to limit the number of threads (concurrent reques
.. note:: This configuration is possible in Jetty as well but not yet documented in this manual.
+
Native JAI and JAI ImageIO
--------------------------
Using the native-code implementation of JAI and JAI ImageIO speeds up GeoServer, thereby requiring less concurrency at the same level of throughput.
The GeoServer manual contains `platform-specific instructions <http://docs.geoserver.org/stable/en/user/production/java.html#install-native-jai-and-jai-image-i-o-extensions>`_ for configuring JAI and JAI ImageIO.
+
GeoServer Configuration
-+++++++++++++++++++++++
+=======================
There are a few controls to be set in the GeoServer configuration itself as well.
+
On the JAI Settings page
-++++++++++++++++++++++++
+------------------------
.. figure:: GeoServer-JAI-Settings.png
@@ -184,8 +269,9 @@ On the JAI Settings page
* Disable Tile Recycling as this optimization is less relevant on recent JVM implementations and has some overhead itself.
+
On the WMS Service page
-+++++++++++++++++++++++
+-----------------------
.. figure:: GeoServer-Web-Map-Service.png
@@ -195,20 +281,47 @@ On the WMS Service page
This sounds a bit counterintuitive, but these limits are implemented in an inefficient way such that unless resource-intensive requests are common on your server it is more efficient to avoid the limits.
A better implementation of this feature is available for GeoServer 2.1 and will be incorporated in GeoNode 1.1.
-Sitemaps Configuration
-----------------------
-GeoNode can automatically generate a sitemap suitable for submission to search
-engines which can help them to index your GeoNode site more efficiently and
-effectively.
+Printing with the Mapfish Print Service
+=======================================
+
+The GeoNode map composer can "print" maps to PDF documents using the `Mapfish
+print service <http://www.mapfish.org/doc/print>`_. The recommended way to run
+this service is by using the printing extension to GeoServer (if you are using
+the pre-built GeoNode package, this extension is already installed for you).
+However, the print service includes restrictions on the servers that can
+provide map tiles for printed maps. These restrictions have a fairly strict
+default, so you may want to loosen these constraints.
+
+Adding servers by hostname
+..........................
+
+.. highlight:: yaml
+
+The Mapfish printing module is configured through a `YAML <yaml>`_
+configuration file, usually named :file:`print.yaml`. If you are using the
+GeoServer plugin to run the printing module, this configuration file can be
+found at :file:`{GEOSERVER_DATA_DIR}/printing/config.yaml`. The default
+configuration should contain an entry like so::
+
+ hosts:
+ - !dnsMatch
+ host: labs.metacarta.com
+ port: 80
+ - !dnsMatch
+ host: terraservice.net
+ port: 80
+
+You can add host/port entries to this list to allow other servers.
+
+.. seealso::
+
+ The `Mapfish documentation
+ <http://www.mapfish.org/doc/print/configuration.html>`_ on configuring the
+ print module.
+
+ The `GeoServer documentation
+ <http://docs.geoserver.org/stable/en/user/community/printing/>`_ on
+ configuring the print module.
-In order to generate the sitemap properly, the sites domain name must be set
-within the sites framework. This requires that an admin user login to the
-admin interface and navigate to the sites module and change example.com to the
-actual domain name (and port if applicable). The admin interface can be accessed
-at http://<host>:<port>/admin/sites/site/
-It is possible to 'inform' google of changes to your sitemap. This is accomplished
-using the ping_google management command. More information can be found here
-http://docs.djangoproject.com/en/dev/ref/contrib/sitemaps/#django.contrib.sitemaps.ping_google
-It is recommended to put this call into a cron (scheduled) job to update google periodically.
View
294 docs/developers/architecture.txt
@@ -0,0 +1,294 @@
+============
+Architecture
+============
+
+This section provides insight about the components of GeoNode and the way they are used to create the final product.
+
+
+Components
+==========
+
+The main components are:
+
+#. **The data manager: GeoServer**
+ GeoServer provides an *OGC* compatible data store that can speak *WMS*, *WFS*, *WCS* and others in common formats like *GML*, *GeoJSON*, *KML* and *GeoTiff*.
+
+ It can be connected to different spatial backends including *PostGIS*, *Oracle Spatial*, *ArcSDE* and others.
+
+
+#. **The catalog: GeoNetwork**
+ GeoNetwork provides a standar catalog and search interface based on *OGC* standars.
+ It is used via the *CSW* interface to create and update records when they are accessed in GeoNode..
+
+#. **The website: GeoNode Django site**
+ This is a Django based project that allows the user to easily tweak the content and look and feel and to extend GeoNode to build Geospatial.
+ It includes tools to handle user registration and accounts, avatars, and helper libraries to interact with GeoServer and GeoNetwork in a programatic and integrated way.
+ There is a wide range of third party apps that can be plugged into a GeoNode based site including tools to connect to different social networks, to build content management systems and more.
+
+
+#. **The map composer: GeoNode client**
+ The main interface for GeoNode is the Map Composer / Editor. It is built on top of *GeoExt* and uses OPenLayers, GXP
+ It talks to the other components via *HTTP* and *JSON* as well as standard *OGC* services.
+
+
+Dependencies
+------------
+
+Here is an indicative list of the projects GeoNode relies on:
+
+ * PostgreSQL
+ * Mapfish printing module
+ * OpenGeo's GXP
+ * gsconfig.py
+ * owslib
+ * django-registration
+ * django-avatar
+ * GeoTools
+
+And for building it makes use of:
+
+ * Paver
+ * Maven
+ * Git
+ * Bash
+
+
+
+GeoNode and GeoNetwork
+======================
+
+customizing the schema used in GeoNetwork
+
+ * adapt Layer metadata in Django, analogous to Django's usual User models
+
+JavaScript in GeoNode
+=====================
+
+GeoNode provides a number of facilities for interactivity in the web browser built on top of several high-quality JavaScript frameworks:
+
+* `ExtJS <http://extjs.com/>`_ for component-based UI construction and data
+ access
+* `OpenLayers <http://openlayers.org/>`_ for interactive mapping and other
+ geospatial operations
+* `GeoExt <http://geoext.org/>`_ for integrating ExtJS with OpenLayers
+* `GXP <http://projects.opengeo.org/gxp>`_ for providing some higher-level
+ application building facilities on top of GeoExt, as well as improving
+ integration with GeoServer.
+* and a GeoNode-specific framework to handle some pages and services that are
+ unique to GeoNode.
+
+The following concepts are particularly important for developing on top of the
+GeoNode's JavaScript framework.
+
+* Components - Ext components handle most interactive functionality in
+ "regular" web pages. For example, the scrollable/sortable/filterable table
+ on the default Search page is a Grid component. While GeoNode does use some
+ custom components, familiarity with the idea of Components used by ExtJS is
+ applicable in GeoNode development.
+
+* Viewers - Viewers display interactive maps in web pages, optionally decorated
+ with Ext controls for toolbars, layer selection, etc. Viewers in GeoNode use
+ the GeoExplorer base class, which builds on top of GXP's Viewer to provide
+ some common functionality such as respecting site-wide settings for
+ background layers. Viewers can be used as components embedded in pages, or
+ they can be full-page JavaScript applications.
+
+* Controls - Controls are tools for use in OpenLayers maps (such as a freehand
+ control for drawing new geometries onto a map, or an identify control for
+ getting information about individual features on a map.) GeoExt provides
+ tools for using these controls as ExtJS "Actions" - operations that can be
+ invoked as buttons or menu options or associated with other events.
+
+GeoNode and GeoServer
+=====================
+
+GeoNode uses GeoServer to convert geographic data between various file formats,
+as well as render styled map tiles. While standard GeoServer components,
+including its OGC-compliant web services and REST configuration API, provide
+the bulk of the GeoServer functionality used in a GeoNode site, there are some
+extensions to help GeoServer and the Django application interoperate more
+better.
+
+Geoprocessing with the GeoServer Process Extension
+--------------------------------------------------
+
+The Process extension to GeoServer helps to define custom geoprocessing
+operations against data managed by GeoServer. The operations are exposed via a GeoServer RESTlet endpoint.
+
+Some processes are included with the Process extension. Defining your own
+processes is possible too, but first let's look at how to use the processes
+that are already present.
+
+There are two 'modes' of accessing these processes: *interactive* and *batch*.
+The *interactive* mode is appropriate for fast-running processes and returns
+the result of the operation as the HTTP response to the request that launches
+the process. The *batch* mode starts a thread on the server and supports
+polling to find out information about progress until the process is completed.
+
+Interactive Mode Processing
+...........................
+
+To use interactive-mode processing:
+
+ * send an HTTP POST request with the process parameters to
+ /geoserver/rest/process/{process}/ . The parameters must be formatted as a
+ JSON document.
+
+ * The result of the process will be returned, or an error will be reported
+ via the HTTP status code (500 for a general error, 400 for a badly
+ formatted request, etc.) While the format of this response varies with the
+ process, JSON should be preferred for structured, machine-accessible
+ responses.
+
+Batch Mode Processing
+.....................
+
+To use batch-mode processing:
+
+ * send an HTTP POST with the process parameters to
+ /geoserver/rest/process/{process}/launch . The parameters must be
+ formatted as a JSON document as described in the section on interactive
+ mode. The reponse will contain a document describing the process's
+ progress, including an {id} string that identifies the process for future
+ reference.
+
+ * The process will initially be in a queue. You can check on its progress by
+ sending an HTTP GET request to /geoserver/rest/processes/{id}/status .
+ When the status is DONE, you can send an HTTP GET request to
+ /geoserver/rest/processes/{id}/result.
+
+ * If you find a reason to cancel (for example, the user closes the JS widget
+ that launched the process request), you can cancel by sending a DELETE
+ request to /geoserver/rest/processes/{id} . This will free up resources
+ sooner, but in either case GeoServer will automatically delete cached
+ process results after a set period, so you should ensure that you present
+ the results to the user in a prompt fashion via some means or other.
+
+Custom Processes
+................
+
+To create a custom process:
+
+#. Write a Java class that extends the Process interface. It can use GeoTools,
+ and has access to the GeoServer catalog. Let's call it
+ ``com.example.custom.Process``. Aditionally, subclass ``ProcessRestlet`` to
+ create a Restlet that invokes your Process.
+
+#. Include a Spring context XML file called ``applicationContext.xml`` that
+ defines a bean using your process class, and a restlet mapping that attaches
+ your process to a specific URL pattern. An example would be:
+
+ .. code-block:: xml
+
+ <beans>
+ <bean class="com.example.custom.ProcessRestlet" id="exampleRestlet"/>
+ <bean class="org.geoserver.rest.RESTMapping" id="exampleMapping">
+ <property name="routes">
+ <map>
+ <entry>
+ <key><value>/process/example</value></key>
+ <value>exampleRestlet</value>
+ </entry>
+ </map>
+ </bean>
+ </beans>
+
+#. Make sure that the JAR containing your process is on the Java classpath when
+ your application is running by including it in the ``WEB-INF/lib`` directory
+ of your GeoServer WAR file.
+
+Authentication/Authorization
+----------------------------
+
+.. warning::
+
+ This section describes features which have not yet been implemented.
+
+GeoNode also provides an extension to GeoServer to have it respect GeoNode's
+user database and permissions instead of its own independent system. This
+extension allows GeoServer to authenticate users by HTTP Basic auth (good for
+general desktop GIS applications) or Django session cookies (good for users
+accessing GeoServer from the Django site.) The basic strategy is for GeoServer
+to forward either type of credential to a Django web service which provides
+GeoServer with up-to-date information about the user's permissions. Consider a
+request coming into some GeoServer service::
+
+ GET /geoserver/ows?request=GetFeature&typename=top_secret:data
+
+GeoServer will first inspect the request to identify whether it contains an
+``Authorization:`` header or a cookie from the Django session system.
+GeoServer then issues a request to Django::
+
+ GET /user/permissions
+
+Including the credentials it found on the initial request. If the
+``Authorization:`` header contains the username and password for a valid user,
+or the session cookie corresponds to an active session for a logged-in user,
+then Django responds with a document describing the permissions associated with
+that user. If the ``Authorization:`` header or cookie is found and determined
+to be invalid, then Django sets a 401 status on the HTTP response. Otherwise,
+Django assumes an anonymous user and returns a document describing the
+permissions associated with anonymous users. The permissions document is a
+JSON object that looks like this::
+
+ {
+ "rw": ["prefix:name", "prefix:name"],
+ "ro": ["prefix:name", "prefix:name"]
+ }
+
+That is, a top-level object with two keys:
+
+``rw``
+ an array of prefixed layer names of layers which should be fully available
+ (both read and write) to this user
+
+``ro``
+ an array of prefixed layer names of layers which should be displayed to this
+ user, but which he/she should not be able to modify
+
+All layers not named in this response will be presumed fully restricted, that
+is, neither modifiable nor visible to the user in question.
+
+Printing with the Mapfish Print Service
+---------------------------------------
+
+The GeoNode map composer can "print" maps to PDF documents using the `Mapfish
+print service <http://www.mapfish.org/doc/print>`_. The recommended way to run
+this service is by using the printing extension to GeoServer (if you are using
+the pre-built GeoNode package, this extension is already installed for you).
+However, the print service includes restrictions on the servers that can
+provide map tiles for printed maps. These restrictions have a fairly strict
+default, so you may want to loosen these constraints.
+
+Adding servers by hostname
+..........................
+
+.. highlight:: yaml
+
+The Mapfish printing module is configured through a `YAML <yaml>`_
+configuration file, usually named :file:`print.yaml`. If you are using the
+GeoServer plugin to run the printing module, this configuration file can be
+found at :file:`{GEOSERVER_DATA_DIR}/printing/config.yaml`. The default
+configuration should contain an entry like so::
+
+ hosts:
+ - !dnsMatch
+ host: labs.metacarta.com
+ port: 80
+ - !dnsMatch
+ host: terraservice.net
+ port: 80
+
+You can add host/port entries to this list to allow other servers.
+
+.. seealso::
+
+ The `Mapfish documentation
+ <http://www.mapfish.org/doc/print/configuration.html>`_ on configuring the
+ print module.
+
+ The `GeoServer documentation
+ <http://docs.geoserver.org/stable/en/user/community/printing/>`_ on
+ configuring the print module.
+
+
View
52 docs/developers/contribute.txt
@@ -0,0 +1,52 @@
+Contributing to GeoNode
+=======================
+
+## THIS IS A DRAFT PROPOSAL. IT HAS NOT YET BEEN VOTED INTO EFFECT BY THE PSC.
+
+If you are interested in helping us to make GeoNode, there are many ways to do so.
+
+Participate in the Discussion
+-----------------------------
+
+GeoNode has a mailing list (geonode@librelist.org) where users can ask and answer questions about the software.
+There is also an IRC chat room on [Freenode](http://freenode.net/) where users and developers can discuss GeoNode in real time.
+Sometimes users also post interesting tips for managing sites running GeoNode.
+If you want to help out with GeoNode, one easy way is to sign up for the mailing list and help answer questions.
+
+Report Problems
+---------------
+
+While we do our best to keep GeoNode fast and bug-free, problems can and do arise.
+Informative bug reports are a key part of the bug fixing process, so if you do run into a problem with GeoNode, please don't hesitate to report it on our bug tracker, available online at [[http://dev.geonode.org/trac]].
+Useful information for bug reports includes:
+
+ * What were you doing when the bug occurred?
+ Does the problem occur every time you do that, or only occasionally?
+ * What were you expecting to happen?
+ What happened instead?
+ * What version of the software are you using?
+ Please also note any changes from the default configuration.
+ * If there is a data file involved in the bug (such as a Shapefile that doesn't render properly), please consider including it in the bug report.
+ We do respect that not all data files are freely distributable.
+
+Write Documentation
+-------------------
+
+GeoNode's documentation can always use improvement - there are always more questions to be answered.
+For managing contributions to the manual, GeoNode uses a process similar to that used for managing the code itself.
+The documentation is generated from source files in the `docs/` directory within the GeoNode source repository.
+See [[http://sphinx.pocoo.org/]] for more information on the documentation system we use.
+
+Provide Translations
+--------------------
+
+If GeoNode doesn't provide a user interface in your native language, consider contributing a new translation file.
+See [[https://docs.djangoproject.com/en/1.2/topics/i18n/]] for an overview of the internationalization system used in GeoNode.
+
+Write Code
+----------
+
+Of course since GeoNode is an open source project we do encourage contributions of source code as well.
+If you are interested in making small changes, you can find an open ticket on [[http://dev.geonode.org/trac/]], hack away, and get started on the [[Patch Review Process]].
+
+
View
210 docs/developers/extend.txt
@@ -0,0 +1,210 @@
+=================
+Extending GeoNode
+=================
+
+This page provides a high-level description of what have emerged as "Best
+Practices" for extending or building on top of the GeoNode platform. While
+there are other ways to accomplish this, several key existing projects
+(see below) now follow this methodology after much trial-and-error, and it's
+now agreed to be the *best* way to extend from GeoNode in order to add
+functionality or to customize the site.
+
+TODO: Some notes here about the goal of easily upgrading to new GeoNode Releases
+
+Existing Projects using this Methodology
+========================================
+* Risiko (https://github.com/AIFDR/riab)
+* TsuDAT (https://github.com/aifdr/tsudat2)
+* HaitiData (https://github.com/GFDRR/haitidata)
+* OpenRDI (https://github.com/GFDRR/openrdi)
+* OpenSanDiego Maps (https://github.com/ortelius/mapsosd)
+
+Pre-requisites
+==============
+
+* Working GeoNode installation see :doc:`/intro/install`.
+* Familiarity with Django and its project layout scheme
+ https://docs.djangoproject.com/en/dev/intro/tutorial01/
+
+
+Setup Steps
+===========
+
+1. *Upgrade GeoNode:* First and foremost, you should upgrade GeoNode to the
+ latest release. GeoNode releases can be found here
+ http://dev.geonode.org/release/ There are deployment scripts that make
+ this process much easier, they can be found here ???
+
+2. *Source GeoNode's virtualenv:* While your new project will be a Django
+ project in it own right, it needs to have access to all the dependencies
+ you already installed as part of GeoNode into a virtual environment
+ (link to venv docs). You can *activate* that virtual environment and make
+ those dependencies available with the following command::
+
+ $ source /var/www/geonode/wsgi/geonode/bin/activate
+
+ This may need to be modified if you installed in a non-standard location.
+
+3. *Setup Your Project Directory:* Your new project needs to follow Django's
+ conventions for a project, and this is most easily accomplished by using
+ Django's management commands specifically setup for this purpose. To use
+ these commands, change directories into the place where you want your
+ project to live and issue the following command, replacing
+ <your_project_name> with the name for your new project::
+
+ $ django-admin.py startproject <your_project_name>
+
+ It is recommended that you immediately place your project under revision
+ control, and it's further recommended that you use Git and GitHub. Once
+ your project is created with the startproject management command, you can
+ setup your project in github by following the instructions here.
+ http://help.github.com/create-a-repo/
+
+4. *Copy key files from GeoNode into your project dir:* Once your new Django
+ project is setup, you need to copy some key files from GeoNode into your
+ projects top level directory. Change directories into the new directory
+ created by the startproject management command and issue the following
+ commands::
+
+ $ cp /var/www/geonode/wsgi/geonode/src/GeoNodePy/geonode/settings.py .
+ $ cp /var/www/geonode/wsgi/geonode/src/GeoNodePy/geonode/local_settings.py .
+ $ cp /var/www/geonode/wsgi/geonode/src/GeoNodePy/geonode/urls.py .
+
+ You will be modifying these files as part of the process of extending
+ GeoNode or customizing it for your own purposes.
+
+5. *Modify settings.py file:* The first file that needs to be modified is the
+ main settings file. You need to add a few lines to it in order to make
+ it suitable for use in your project.
+
+ Basic Settings::
+
+ import geonode
+
+ PROJECT_ROOT = os.path.abspath(os.path.dirname(__file__))
+ GEONODE_ROOT = os.path.dirname(geonode.__file__)
+
+ Media settings (ingenieroariel, looking for input here)::
+
+ MEDIA_ROOT = os.path.join(PROJECT_ROOT, "uploads")
+ MEDIA_URL = "/uploads/"
+ GEONODE_UPLOAD_PATH = os.path.join(MEDIA_ROOT, "geonode")
+ STATIC_ROOT = os.path.join(PROJECT_ROOT, "static")
+ STATIC_URL = "/static/"
+ GEONODE_CLIENT_LOCATION = STATIC_URL + "geonode/"
+ ADMIN_MEDIA_PREFIX = os.path.join(STATIC_URL, "admin/")
+ STATICFILES_DIRS = [
+ os.path.join(PROJECT_ROOT, "media"),
+ os.path.join(GEONODE_ROOT, "media"),
+ ]
+
+ Template Directories::
+
+ TEMPLATE_DIRS = (
+ os.path.join(PROJECT_ROOT,"templates"),
+ os.path.join(GEONODE_ROOT,"templates"),
+ )
+
+ GEOSERVER_TOKEN
+
+6. *Install dependencies for your project:* If your project requires additional
+ dependencies that are not installed as part of GeoNode, you should create a
+ requirements.txt file and include them inside. A requirements.txt file is
+ simply a text file that includes the name of a library or app that can be
+ installed with easy_install or pip. Documentation on the requirements file
+ format can be found here http://www.pip-installer.org/en/latest/#requirements-files
+ An example is below::
+
+ django-rosetta
+ django-flatblocks
+ django-modeltranslation
+
+ When the requirements file is in place, and the virtualenv is activated
+ (see step 2 above), you can install the additional dependencies with the
+ following command::
+
+ $ pip install -e requirements.txt
+
+ If any of these requirements are django apps (as in the above example),
+ they need to be added to the INSTALLED_APPS section of your settings.py
+ file::
+
+ INSTALLED_APPS = (
+ 'django.contrib.auth',
+ 'django.contrib.contenttypes',
+ 'django.contrib.sessions',
+ 'django.contrib.sites',
+ 'django.contrib.admin',
+ 'django.contrib.staticfiles',
+ 'django_extensions',
+ 'registration',
+ 'profiles',
+ 'avatar',
+ 'geonode.core',
+ 'geonode.maps',
+ 'geonode.proxy',
+ 'rosetta',
+ 'flatblocks',
+ 'modeltranslation',
+ )
+
+7. *Syncdb:* If the additional dependencies you have installed in the steps above
+ are django apps that will use the Django ORM to store and retrieve data in
+ a database, you need to execute the syncdb management command to create the
+ tables in the database. This can be done with the following command::
+
+ $ django-admin.py syncdb
+
+8. *Copy GeoNodes wsgi script and modify it for your project:* The GeoNode application
+ is executed and served apache using a wsgi launcher script. You will need to make
+ a copy of this launcher script and modify it to execute your newly created project.
+ It is generally a good idea to place this wsgi launcher script in a directory under
+ the main directory of your new project. This can be done with the following commands::
+
+ $ mkdir wsgi
+ $ cp /var/www/geonode/wsgi/geonode.wsgi wsgi/<new_project_name>.wsgi
+
+ Replacing <new_project_name> with the name of your newly created project.
+
+ Once this file is in place, it needs to be modified to execute your new project when
+ being run via apache. The following line should be added replacing /var/www with the
+ path to where your new project is located::
+
+ site.addsitedir('/var/www')
+
+ The existing line that specifies which settings module to use should be modified
+ to point at your settings. <new_project_name> should be replaced by the name of your
+ new project::
+
+ os.environ['DJANGO_SETTINGS_MODULE'] = '<new_project_name>.settings'
+
+8. *Configure apache to use your own wsgi script:* Once your new wsgi launcher script is
+ modified and ready for use, you need to setup apache to use this script instead of the
+ original geonode one. Depending on your platform, the file containing the WSGIScriptAlias
+ directive will vary. Please consult the :doc:`/intro/install` documentation. This directive
+ should be modified to point at your newly created wsgi script::
+
+ WSGIScriptAlias / "/var/www/<new_project_dir>/wsgi/<new_project_name>.wsgi"
+
+ Replacing <new_project_dir> with the path to your newly created project, and
+ <new_project_name> with the name of your project.
+
+9. *Begin Customizing/Extending:* You are now ready to begin modifying GeoNode to extend
+ or customize it. You may need to redo some of the steps above if you need to add new
+ dependencies or change directives in the settings.py file.
+
+
+Types of Customization/Extension
+================================
+
+Branding
+--------
+
+Adding Additional Django Pluggable Apps
+---------------------------------------
+
+Adding your own Django Apps
+---------------------------
+
+???
+---
View
78 docs/developers/gnips.txt
@@ -0,0 +1,78 @@
+# GeoNode Improvement Proposals
+
+GeoNode Improvement Proposals (GNIP) are the formal mechanism used to manage any sort of major change to GeoNode.
+While the definition of "major" is subject to interpretation, examples of changes which are managed by the GNIP process include:
+
+* Redesign or implementation of major features
+* Code re-architecture
+* Changes to GeoNode process or project policy
+
+Only committers may submit a GeoNode Improvement Proposal.
+Non-commiters are encouraged to find a committer to sponsor their idea and guide them through the process.
+If there is ever a question as to whether a proposal should be written, please ask on the list.
+
+Unlike the patch review process, the Improvement Proposal process has no special treatment for committers or even for Project Steering Committee members.
+The reason for this is that improvement proposal review serves another purpose besides ensuring changes made are acceptable to the community: it also gives GeoNode stakeholders time to consider and plan for large changes before they happen.
+
+The [[Patch Review Process]] is related.
+ While the Improvement Proposal process is intended to promote coordinated design and feedback for far-reaching modification such as core architectural changes, the code review process protects code quality in the GeoNode project at a fine granularity.
+
+
+
+How a GNIP works
+----------------
+
+The typical life cycle of a GNIP is as follows:
+
+1. Developer has an intent to perform a major change
+
+2. Developer communicates with the community about the change
+
+3. Developer goes off and implements the change
+
+4. Developer writes a GNIP and presents it to the community for feedback
+
+5. The PSC votes on the GNIP.
+ If the GNIP author is also a member of the PSC, he should still vote.
+
+6. Developer commits changes upon receiving a positive vote
+
+Voting on a GNIP
+----------------
+
+One of the duties of the Geonode Project Steering Committee is to vote on GSIPs.
+The voting process works as follows:
+
+* The voting system used is the Apache consensus system.
+ Each PSC member gets a single vote, which can be one of +1, -1, 0.
+
+* Any PSC member that votes negatively against a proposal must provide a reasonable explanation as to why. In general, reasonable negative votes should be based on criteria listed in [[Review Criteria]].
+
+* Any PSC member that votes negatively against a proposal has a limited time to provide constructive feedback as to how the vote can be turned
+
+* The GNIP author must incorporate any reasonable feedback into the proposal
+
+* Any negative vote is reviewed to determine if criteria has been met to turn it to a positive vote
+
+* The proposal is considered successful after a majority of positive votes is a achieved **and** all feedback from any negative votes has been addressed
+
+Non-PSC members of the GeoNode community are encouraged to participate in GNIP review, but a negative vote does not block the realization of the proposal unless it comes from a steering committee member.
+
+Implementing a GNIP
+-------------------
+
+In order to maintain records of design discussions, proposals must be submitted as pages on the GeoNode wiki.
+To make a proposal:
+
+2. Log in to the wiki and create a new page.
+
+4. Name the new page "GSIP ## - <TITLE>" where:
+
+ * ## is the number of the GSIP, determined simply by adding 1 to the highest-numbered existing proposal.
+
+ * <TITLE> is the title of the GSIP
+
+5. Fill in the information in the page template, and click ``Save`` when complete.
+
+3. Link to the new page from the [[Proposals Under Discussion]] page.
+
View
57 docs/developers/patches.txt
@@ -0,0 +1,57 @@
+GeoNode Patch Review Process
+============================
+
+This document outlines the code review process for GeoNode code.
+Each commit proposed for inclusion in GeoNode should be reviewed by at least one developer other than the author.
+For pragmatic reasons, some developers, referred to in this document as *core committers*, may commit directly to the GeoNode repository without waiting for review.
+Such changes are still subject to review, and may be reverted if they fail any of the [[Review Criteria]].
+
+A related process is [[Improvement Proposals]].
+While patch review protects code quality in the GeoNode project at a small granularity, the Improvement Proposal process is intended to promote coordinated design and feedback for larger modifications such as new features or architectural changes.
+
+Goals
+-----
+
+By requiring a review of code coming into GeoNode, we aim to maintain code quality within the GeoNode project while still allowing contributions from the GeoNode community.
+
+
+Review Criteria
+---------------
+
+Patch reviews should adhere to the standards set in the [[Review Criteria]], a [[Project Steering Committee]] approved set of criteria for the inclusion of new code.
+
+
+Process
+-------
+
+For contributors who do not have commit access to the GeoNode repository, the review process is as follows:
+
+0. Find or create a ticket describing the feature or bug to be resolved.
+1. Create changes to GeoNode code addressing the ticket.
+2. Publish those changes and request a review from the GeoNode committers.
+ The recommended format is a GitHub [pull request](http://help.github.com/pull-requests/).
+ If you are unable or unwilling to provide a change as a branch on GitHub, please consult the developer's list for advice.
+3. At least one GeoNode committer should review the submitted changes.
+ If he finds the patch acceptable, the changes will be pulled into GeoNode.
+ If problems are found, then he should list them clearly in order to allow the original author to update the submission (at which point we return to point 2 in this process.)
+ In the case of a feature idea which is simply not suitable for inclusion as core GeoNode functionality, the patch may be rejected outright.
+
+![Code Review Flow](http://geonode.org/wp-content/uploads/2011/05/code-review-flow.png)
+
+ The general workflow for code patches coming into GeoNode.
+
+_Note: If after a few days your patch has not been reviewed by any GeoNode committer, please feel free to bring it up either in the mailing list or the IRC channel. The GeoNode community (and it's committers) try to respond quickly and give adequate feedback to maintain the interest of new potential members. However, sometimes other responsibilities prevent us from responding quickly._
+
+Core Committers
+---------------
+
+It is assumed that core committers are familiar with the quality guidelines and capable of producing acceptable patches without the need for waiting on review.
+Therefore, core committers may make changes without requesting review first (although they are welcome to request review for code if they feel it is appropriate.)
+For commits made without prior review, committers should review the changes and revert them if they are in violation of the project quality guidelines.
+
+Becoming a Core Committer
+-------------------------
+
+In order for a developer to become a core committer, he must demonstrate familiarity with the quality guidelines for the GeoNode project by producing at least two patches which successfully pass review and are merged without requiring modification.
+A candidate for core committer-ship must be nominated by a member of the [[Project Steering Committee]], and approved via Apache consensus voting among PSC members.
+
View
80 docs/source/django-apps/maps.rst → docs/developers/reference/django-apps.txt
@@ -1,3 +1,60 @@
+===================
+GeoNode Django Apps
+===================
+
+The user interface of a GeoNode site is built on top of the Django web
+framework. GeoNode includes a few "apps" (reusable Django modules) to support
+development of those user interfaces. While these apps have reasonable default
+configurations, for customized GeoNode sites you will probably want to adjust
+these apps for your specific needs.
+
+.. toctree::
+ :maxdepth: 2
+
+ django-apps/core
+ django-apps/maps
+ django-apps/proxy
+
+.. comment:
+
+ geonode.core
+ Provide site navigation support and other miscellaneous tasks
+
+ geonode.maps
+ manage layers, maps, styles
+
+ geonode.proxy
+ support JavaScript applications accessing GeoServer/GeoNetwork
+
+
+``geonode.core`` - Miscellaneous site utilities
+===============================================
+
+This Django app provides some basic website features in an extensible fashion.
+For example, many sites should be able to add tabs to the site navigation bar
+without having to modify templates by taking advantage of the navigation
+features provided by this module.
+
+``settings.py`` Entries
+-----------------------
+
+MEDIA_LOCATIONS
+ GeoNode uses a lot of JavaScript and CSS includes due to the distribution
+ restrictions imposed by ExtJS. The MEDIA_LOCATIONS settings file should be a
+ Python dict providing mappings from abstracted library prefixes to actual
+ media URLs, suitable for use in the site. To see the prefix names used in
+ the default templates, an example, consult the settings.py for the example
+ ``geonode`` site included in the source tree.
+
+Template Tags
+-------------
+geonode_media <media_name>
+ Accesses entries in MEDIA_LOCATIONS without requiring the view to explicitly
+ add it to the template context. Example usage::
+
+ {% include geonode_media %}
+ {% geonode_media "ext_base" %}
+
``geonode.maps`` - Map creation and geospatial data management
==============================================================
@@ -82,3 +139,26 @@ GOOGLE_API_KEY
updatelayers
Scan GeoServer for data that hasn't been added to the GeoNode yet, and ensure
that each layer in the Django database is indexed in GeoNetwork
+
+``geonode.proxy`` - Assist JavaScript applications in accessing remote servers
+==============================================================================
+
+This Django app provides some HTTP proxies for accessing data from remote
+servers, to overcome restrictions imposed by the same-origin policy used by
+browsers. This helps the GeoExt applications in a GeoNode site to access various XML documents from OGC-compliant data services.
+
+Views
+-----
+
+geonode.proxy.views.proxy
+ This view forwards requests without authentication to a URL provided in the
+ request, similar to the proxy.cgi script provided by the OpenLayers project.
+
+geonode.proxy.views.geoserver
+ This view proxies requests to GeoServer. Instead of a URL-encoded URL
+ parameter, the path component of the request is expected to be a path
+ component for GeoServer. Requests to this URL require valid authentication
+ against the Django site, and will use the GEOSERVER_CREDENTIALS and
+ GEOSERVER_BASE_URL settings as defined in the maps application.
+
+
View
42 docs/source/geoserver-extensions.rst → docs/developers/reference/geoserver.txt
@@ -1,3 +1,4 @@
+=====================
GeoNode and GeoServer
=====================
@@ -148,44 +149,3 @@ That is, a top-level object with two keys:
All layers not named in this response will be presumed fully restricted, that
is, neither modifiable nor visible to the user in question.
-Printing with the Mapfish Print Service
----------------------------------------
-
-The GeoNode map composer can "print" maps to PDF documents using the `Mapfish
-print service <http://www.mapfish.org/doc/print>`_. The recommended way to run
-this service is by using the printing extension to GeoServer (if you are using
-the pre-built GeoNode package, this extension is already installed for you).
-However, the print service includes restrictions on the servers that can
-provide map tiles for printed maps. These restrictions have a fairly strict
-default, so you may want to loosen these constraints.
-
-Adding servers by hostname
-..........................
-
-.. highlight:: yaml
-
-The Mapfish printing module is configured through a `YAML <yaml>`_
-configuration file, usually named :file:`print.yaml`. If you are using the
-GeoServer plugin to run the printing module, this configuration file can be
-found at :file:`{GEOSERVER_DATA_DIR}/printing/config.yaml`. The default
-configuration should contain an entry like so::
-
- hosts:
- - !dnsMatch
- host: labs.metacarta.com
- port: 80
- - !dnsMatch
- host: terraservice.net
- port: 80
-
-You can add host/port entries to this list to allow other servers.
-
-.. seealso::
-
- The `Mapfish documentation
- <http://www.mapfish.org/doc/print/configuration.html>`_ on configuring the
- print module.
-
- The `GeoServer documentation
- <http://docs.geoserver.org/stable/en/user/community/printing/>`_ on
- configuring the print module.
View
12 docs/developers/reference/index.txt
@@ -0,0 +1,12 @@
+===================================
+Developer's reference documentation
+===================================
+
+This contains detailed information about the implementation of the different sofware modules in GeoNode
+
+.. toctree::
+ :maxdepth: 2
+
+ django-apps
+ geoserver
+ javascript
View
1 docs/source/geonode-javascript.rst → docs/developers/reference/javascript.txt
@@ -1,3 +1,4 @@
+=====================
JavaScript in GeoNode
=====================
View
47 docs/developers/roadmap.txt
@@ -0,0 +1,47 @@
+=======
+Roadmap
+=======
+
+Roadmap Process
+---------------
+
+The GeoNode Roadmap Process is designed to complement the more technical GeoNode [[Improvement Proposals]] and strives to make it easier for the various organizations invested in GeoNode to collaborate on features of common interest.
+
+It is based on the `roadmap items <https://spreadsheets.google.com/a/opengeo.org/spreadsheet/ccc?key=0AklXlBUnMqOrdDNackdvX3ZRS0Fha0xCeGhjSjZ1dEE>`_ developed at the `GeoNode Roadmapping Summit <http://geonode.org/2011/05/roadmapping-summit/>`_ held in May 2011.
+
+Overall, the process for adding items to the collective roadmap is as follows:
+
+#. Organizational partner has an intent to add a feature to the roadmap
+#. Organizational partner communicates with the `organizational partners list <https://groups.google.com/a/opengeo.org/group/geonode-org/>`_ about the change to gauge interest and determine who else is committed to making it happen
+#. Organizational partner creates a feature specification on the wiki to further flesh out the idea
+#. Organizational partner finds a committer on the `developer list <https://groups.google.com/a/opengeo.org/group/geonode-dev/>`_ to shepherd the roadmap item through the GeoNode [[Improvements Process | Improvement Proposals]]
+
+Each roadmap item will go through four stages:
+
+#. Descriptive Stage (under discussion/"Active")
+#. Technical Stage
+#. Development Stage
+#. Released
+
+After communicating on the `organizational partners list <https://groups.google.com/a/opengeo.org/group/geonode-org/>`_ the roadmap items enters the *Descriptive Stage* and must have a wiki page that lays out the description, user stories, and other interested parties. Optionally, the roadmap item will also include an idea of the difficulty and goals as well as any wireframes, technical diagrams, or prior art.
+
+A roadmap item enters the *Technical Stage* once a committer has been found to shepherd the roadmap item through the [[GNIP | Improvement Proposals]] process, then the wiki page must contain a clear sense of the technical assumptions, requirements or dependencies, and suggested implementation. Some roadmap items may need to be divided into multiple independent GNIP proposals.
+
+Once it passes through the [[GNIP | Improvement Proposals]] process, a roadmap item enters the *Development Stage* on its way to *Release*.
+
+Roadmap Items
+-------------
+
+[["Rock Solid" 1.1 Release]] (Development Stage)
+
+[[Public API's and Interfaces]] (Under discussion)
+
+[[Add Remote WMS Service to Search]] (Under discussion)
+
+[[Time Controls on Map]]
+
+[[Improved Layer Search]]
+
+[[LDAP Authentication]] (Under discussion)
+
+[[Groups]] (Under discussion)
View
228 docs/developers/setup.txt
@@ -0,0 +1,228 @@
+=======================================
+Configuring GeoNode in development mode
+=======================================
+
+
+Build Requirements
+==================
+
+Before starting work on the GeoNode, you will need to have the following
+software installed and in your ``PATH``:
+
+* The git command-line client, version 1.5.3 or higher:
+ - To verify that it is available, run ``git --version`` and verify the
+ version is something like ``git version 1.6.6.1``
+ - If not, you can download one of the installers from http://git-scm.com/ or
+ from your operating system provider.
+
+* The Subversion command-line client, version 1.5 or higher.
+ - To verify that is is available, run ``svn --version`` and verify the output
+ starts with something like ``svn, version 1.6.9 (r901367)``
+ - If not, you can find the appropriate installer at
+ http://subversion.apache.org/packages.html
+
+* The GEOS geometry handling library: http://trac.osgeo.org/geos/
+
+* The GDAL geographic raster access library: http://www.gdal.org/
+
+* The OGR geographic vector data access library: http://www.gdal.org/ogr/
+
+* Sun Java Development Kit 1.5 or Higher:
+ - To verify that it is available, run
+ ``javac -help -version`` and verify that it reports a list of usage flags,
+ ending with a line like ``javac 1.5.0_18`` (the numbers will vary with your
+ installed version).
+ - If not, download from http://java.sun.com/javase/downloads/index.jsp
+ (Make sure to install the *JDK*!)
+
+* Python 2.6:
+ - To verify that it is available, run
+ ``python --version`` and verify that it reports a version number like
+ ``Python 2.6``
+ - If not, download from http://python.org/download/
+ - Python must be compiled w/ SSL support and sqlite support to
+ support the geonode development setup. Installing the sqlite and
+ openssl development headers before building Python will suffice.
+
+* Apache Maven 2.0.10 or Later:
+ - To verify that it is available, run
+ ``mvn -version`` and verify that it reports version information like::
+
+ Maven version: 2.0.10
+ Java version: 1.5.0_18
+ OS name: "linux" version: "2.6.30.8-64.fc11.x86_64" arch: "amd64" Family: "unix"
+
+ - If not, download from http://maven.apache.org/download.html
+
+Additionally, GeoNode uses a number of native-code libraries in Python. You
+can install these libraries manually, or allow the GeoNode setup script to
+compile them for you. In the latter case, you will need to install a C
+compiler such as GCC, as well as any requisite development libraries. GCC
+packages are available for Mac OSX and all Linux distributions; consult your
+operating system provider for installation instructions.
+
+The native libraries needed include:
+
+* PIL http://www.pythonware.com/products/pil/
+
+* ReportLab http://www.reportlab.com/software/opensource/rl-toolkit/
+
+* simplejson http://code.google.com/p/simplejson/
+
+For GCC, packages are available for Mac OSX and all Linux distributions;
+consult your operating system provider for installation instructions. When
+build PIL from source, ensure that you have development libraries available for
+libpng, libjpeg, and libgif if you want to be able to use those formats in your
+GeoNode site.
+
+
+Ubuntu
+------
+
+If you are using Ubuntu Linux, you can configure all the above dependencies by running the following comman::
+
+ sudo apt-get install -y --force-yes openjdk-6-jre-headless
+ sudo apt-get install -y vim zip unzip subversion git-core binutils build-essential python-dev python-setuptools python-imaging python-reportlab gdal-bin libproj-dev libgeos-dev python-urlgrabber python-scipy python-nose pep8 python-virtualenv python-gdal python-pastescript postgresql-contrib libpq-dev gettext python-psycopg2
+ sudo apt-get install -y --force-yes ant --no-install-recommends
+
+
+
+Install
+=======
+
+The following steps should prepare a Python virtual environment for you::
+
+ git clone git://github.com/GeoNode/geonode.git geonode
+ cd geonode
+ git submodule update --init
+ python bootstrap.py --no-site-packages # see note below
+ source bin/activate
+ paver build
+ django-admin.py createsuperuser --settings=geonode.settings
+ paver host
+
+Once fully started, you should see a message indicating the address of your geonode::
+
+ Development GeoNode is running at http://localhost:8000/
+ The GeoNode is an unstoppable machine
+ Press CTRL-C to shut down
+
+
+.. note::
+
+ When running ``python bootstrap.py`` the ``--no-site-packages`` option is
+ not required. If enabled, the bootstrap script will sandbox your virtual
+ environment from any packages that are installed in the system, useful if
+ you have incompatible versions of libraries such as Django installed
+ system-wide. On the other hand, sometimes it is useful to use a version of
+ ReportLab or the Python Imaging Library provided by your operating system
+ vendor, or packaged other than on PyPI. When in doubt, however, just leave
+ this option in.
+
+
+This command::
+
+ django-admin.py createsuperuser --settings=geonode.settings
+
+can be used to create additional administrative user accounts. The administrative control panel is not
+linked from the main site, but can be accessed at http://localhost:8000/admin/
+
+Options
+=======
+
+For JavaScript Developers
+-------------------------
+
+Minified Scripts
+................
+
+JavaScript Developers can switch to using unminified scripts and CSS:
+
+1. Get and run geonode-client:
+
+ $ git clone git://github.com/GeoNode/geonode-client.git geonode-client
+ $ cd geonode-client
+ $ ant init debug
+
+2. Set the GEONODE_CLIENT_LOCATION entry in :file:`src/geonode/settings.py` to
+ ``http://localhost:8080/`` and run paver as described above.
+
+Note that this requires ant (http://ant.apache.org/) in addition to the above
+build requirements.
+
+VirtualBox Setup
+................
+
+To test the application in different browsers in VirtualBox guests, the
+following needs to be done before running ``paver host``:
+
+* Start the guest in VirtualBox. Set the network adapter mode to
+ "Host-only adapter". Then set it back to "NAT".
+
+* On the host, do ifconfig and write down the IP address of the vboxnet0
+ adapter.
+
+* Edit :file:`src/GeoNodePy/geonode/settings.py` and change the line::
+
+ GEOSERVER_BASE_URL="http://localhost:8001/geoserver/"
+
+ to use the IP address you have written down above::
+
+ GEOSERVER_BASE_URL="http://192.168.56.1:8001/geoserver/"
+
+* Make sure to change other http://localhost urls in
+ :file:`src/GeoNodePy/geonode/settings.py` accordingly as well
+
+* To start the web server, run::
+
+ $ paver host -b 192.168.56.1
+
+* Now GeoNode is available in your browser at http://192.168.56.1:8000/
+
+
+For Java Developers
+-------------------
+
+How GeoNode Finds GeoServer
+...........................
+
+Java Developers can point the application at a particular GeoServer instance by
+setting the GEOSERVER_BASE_URL entry in settings.py to the context path of the
+GeoServer instance. This should include the trailing slash. For example, the
+GeoServer used for http://geonode.capra.opengeo.org/ is::
+
+ http://geonode.capra.opengeo.org/geoserver/
+
+The default value is ``http://localhost:8001/geoserver/``. The GeoServer module
+in :file:`src/geonode-geoserver-ext/` is configured to provide a GeoServer
+instance at that port with the following commands::
+
+ cd src/geonode-geoserver-ext/
+ sh startup.sh
+
+.. note::
+ Normally, ``mvn jetty:run-war`` would be sufficient. However, we use the
+ shell script to add some extra parameters to the JVM command-line used to
+ run Jetty in order to workaround a JVM bug that affects GeoNetwork.
+
+If you want to change this service URL, edit :file:`src/geonode/settings.py` and
+change the line::
+
+ GEOSERVER_BASE_URL="http://localhost:8001/geoserver/"
+
+to indicate the GeoServer URL that you want to use.
+
+To run the Django app when Jetty is started independently, use::
+
+ paster serve --reload shared/dev-paste.ini
+
+in the base of your working directory.
+
+Alternative GeoServer Data Directories
+......................................
+
+This server defaults to using :file:`gs-data/` as the data directory by default.
+If you need you need to use an alternative data directory, you can specify it
+by editing ``startup.sh`` to specify a different data directory::
+
+ -DGEOSERVER_DATA_DIR=/home/me/mydata/
View
107 ...source/developers/integration-testing.rst → docs/developers/tests.txt
@@ -1,133 +1,156 @@
-Integration Testing in GeoNode
-==============================
+==================
+Testing in GeoNode
+==================
+
+GeoNode has two suites of tests, the unit tests and the integration tests.
+
+
+Unit tests
+==========
+
+The unit tests come with the GeoNode source code and can be run once it has been installed in development or production mode using the following command::
+
+ django-admin.py test geonode --settings=geonode.settings
+
+
+Integration tests
+=================
GeoNode's integration testing suite requires a full deployment with live data for doing some rigorous testing.
This means that running the integration tests requires deploying GeoServer, GeoNetwork and the Django application, although it is possible to run the tests against those servers running in "development" mode.
To ensure repeatability of the tests, GeoNode should be **fully reset** between runs of the suite.
-The integration test suite itself is maintained in a separate source repository from the main GeoNode code; it is available at http://github.com/GeoNode/geonode-integration.git/ . The command below assume that you have cloned this repository into your working directory.
- $ git clone http://github.com/GeoNode/geonode-integration.git/ geonode-integration
+The integration test suite itself is maintained in a separate source repository from the main GeoNode code; it is available at http://github.com/GeoNode/geonode-integration.git/ . The command below assume that you have cloned this repository into your working directory.::
+ git clone http://github.com/GeoNode/geonode-integration.git/ geonode-integration
Running against Paster and Tomcat Standalone
-============================================
+--------------------------------------------
.. note::
This configuration is good for Python developers who can afford to trade away ease of WAR redeployment for faster startup time.
Setup
-.....
+~~~~~
-1: Fetch a standalone archive of Tomcat from http://tomcat.apache.org/ and unpack it::
+#. Fetch a standalone archive of Tomcat from http://tomcat.apache.org/ and unpack it::
- $ wget http://www.trieuvan.com/apache/tomcat/tomcat-6/v6.0.32/bin/apache-tomcat-6.0.32.zip
- $ unzip apache-tomcat-6.0.32.zip
+ wget http://www.trieuvan.com/apache/tomcat/tomcat-6/v6.0.32/bin/apache-tomcat-6.0.32.zip
+ unzip apache-tomcat-6.0.32.zip
-2. Deploy GeoServer and GeoNetwork into the Tomcat ``webapps`` directory by copying the unpacked ZIP archives into the Tomcat ``webapps`` directory::
- $ unzip geonode/webapps/geonetwork.war -d webapps/geonetwork/
- $ unzip geonode/src/geoserver-geonode-ext/target/geoserver-geonode-ext.zip -d webapps/geoserver/
+#. Deploy GeoServer and GeoNetwork into the Tomcat ``webapps`` directory by copying the unpacked ZIP archives into the Tomcat ``webapps`` directory::
- .. note::
+ unzip geonode/webapps/geonetwork.war -d webapps/geonetwork/
+ unzip geonode/src/geoserver-geonode-ext/target/geoserver-geonode-ext.zip -d webapps/geoserver/
- Renaming the GeoNode webapp from ``geoserver-geonode-ext`` to ``geoserver`` matches more closely with the default configuration; if you choose a different name you should modify your ``local_settings.py`` to reflect that.
-3. As GeoNetwork and GeoServer are modified you will need to periodically redeploy to Tomcat.
- You can do so by re-running the ``paver build`` command and then repeating step 2 above.
+.. note:: Renaming the GeoNode webapp from ``geoserver-geonode-ext`` to ``geoserver`` matches more closely with the default configuration; if you choose a different name you should modify your ``local_settings.py`` to reflect that.
+
+#. As GeoNetwork and GeoServer are modified you will need to periodically redeploy to Tomcat.
+ You can do so by re-running the ``paver build`` command and then repeating the previous step.
+
Resetting Before Test Runs
-..........................
+~~~~~~~~~~~~~~~~~~~~~~~~~~
GeoNetwork, GeoServer, and the Django application should all be reset between runs of the integration testing suite.
**Reset Django** by issuing the following command::
- (geonode) $ django-admin.py flush --settings=geonode.settings --noinput \
- && django-admin.py loaddata geonode-integration/admin.fixture.json --settings=geonode.settings
+ geonode flush --noinput
+ geonode loaddata geonode-integration/admin.fixture.json
**Reset GeoServer** by deleting the data/ directory and replacing it with a clean copy::
- $ rm -rf apache-tomcat-6.0.32/webapps/geoserver/data/ && \
- cp -R geonode/gs-data/ apache-tomcat-6.0.32/webapps/geoserver/data/
+ rm -rf apache-tomcat-6.0.32/webapps/geoserver/data/
+ cp -R geonode/gs-data/ apache-tomcat-6.0.32/webapps/geoserver/data/
**Reset GeoNetwork** by erasing the builtin database's storage directory::
- $ rm -rf apache-tomcat-6.0.32/webapps/geonetwork/WEB-INF/db/data/
+ rm -rf apache-tomcat-6.0.32/webapps/geonetwork/WEB-INF/db/data/
After resetting, start Tomcat with::
- $ apache-tomcat-6.0.32/bin/catalina.sh run
+ apache-tomcat-6.0.32/bin/catalina.sh run
and paster with::
- (geonode) $ paster serve --reload shared/dev-paste.ini
+ paster serve --reload shared/dev-paste.ini
For subsequent test runs, it is safe to leave paster running, but Tomcat should be **shutdown before each reset** and not started until the data has been fully refreshed.
+
Run Tests
-.........
+~~~~~~~~~
The integration suite assumes that the ``updatelayers`` command has already been run, so do that::
- (geonode) $ django-admin.py updatelayers --settings=geonode.settings
+ geonode updatelayers
Then the test suite can be run using the included ``runtests.sh`` script::
- $ cd geonode-integration && GEONODE_HOME=../geonode bash runtests.sh
+ cd geonode-integration
+ GEONODE_HOME=../geonode bash runtests.sh
+
Running against Paster and Jetty
-================================
+--------------------------------
.. note::
This configuration is recommended for developers who are doing Java development and need to frequently deploy rebuilt versions of GeoServer and/or GeoNetwork.
+
Setup
-.....
+~~~~~
1. Make a local backup of the sample ``gs-data`` which is downloaded during the ``paver build`` process::
- $ cp gs-data/ -R gs-data.bk/
+ cp gs-data/ -R gs-data.bk/
+
Resetting Before Test Runs
-..........................
+~~~~~~~~~~~~~~~~~~~~~~~~~~
GeoNetwork, GeoServer, and the Django application should all be reset between runs of the integration testing suite.
**Reset Django** by issuing the following command::
- (geonode) $ django-admin.py flush --settings=geonode.settings --noinput \
- && django-admin.py loaddata geonode-integration/admin.fixture.json --settings=geonode.settings
+ geonode flush --noinput
+ geonode loaddata geonode-integration/admin.fixture.json
**Reset GeoServer** by deleting the data/ directory and replacing it with a clean copy::
- $ rm -rf gs-data/ && cp -R gs-data.bk/ gs-data/
+ rm -rf gs-data/ && cp -R gs-data.bk/ gs-data/
**Reset GeoNetwork** by deleting the deployed web application and redeploying it::
- $ rm -rf webapps/geonetwork && \
- unzip webapps/geonetwork.war -d webapps/geonetwork
+ rm -rf webapps/geonetwork
+ unzip webapps/geonetwork.war -d webapps/geonetwork
After resetting, start Tomcat with::
- $ cd src/geoserver-geonode-ext/
- $ sh startup.sh
+ cd src/geoserver-geonode-ext/
+ sh startup.sh
and paster with::
- (geonode) $ paster serve --reload shared/dev-paste.ini
+ paster serve --reload shared/dev-paste.ini
For subsequent test-runs, it is safe to leave paster running, but Tomcat should be **shutdown before each reset** and not started until the data has been fully refreshed.
+
Run Tests
-.........
+~~~~~~~~~
The integration suite assumes that the ``updatelayers`` command has already been run, so do that::
- (geonode) $ django-admin.py updatelayers --settings=geonode.settings
+ django-admin.py updatelayers --settings=geonode.settings
Then, the test suite can be run using the included ``runtests.sh`` script::
- $ cd geonode-integration && GEONODE_HOME=../geonode bash runtests.sh
+ cd geonode-integration
+ GEONODE_HOME=../geonode bash runtests.sh
View
85 docs/index.txt
@@ -0,0 +1,85 @@
+.. GeoNode documentation master file, created by
+ sphinx-quickstart on Mon Oct 3 16:20:38 2011.
+
+========================
+GeoNode's documentation!
+========================
+
+First Steps
+===========
+
+The following documents give an overview to GeoNode, the overview document is targeted at non-technical audiences and the quick installation guide at people who just want to get it installed and will come back later to the complete documentation.
+
+ * :doc:`Overview <intro/overview>`
+ * :doc:`Installation <intro/install>`
+
+.. _the geonode demo site: http://demo.geonode.org
+
+
+For users
+=========
+
+Users are not required to have experience with GIS systems but most power GeoNode users have existings knowledge of tools like ESRI's ArcGIS or qGIS.
+
+The end user documentation is formatted in form of tutorials, this material has mostly been developed for Workshops during FOSS4g and similar conferences.
+
+ * :doc:`Tutorials overview <users/index>`
+ * :doc:`Registering a new account <users/register>`
+ * :doc:`Uploading data <users/upload>`
+ * :doc:`Creating maps <users/create>`
+ * :doc:`Exploring maps <users/explore>`
+ * :doc:`Sharing and printing <users/share>`
+
+
+For Administrators
+==================
+
+Administrators are expected to have some experience with Linux systems but they are not required to be software developers.
+
+ * :doc:`Complete installation guide <deploy/install>`
+ * :doc:`Post installation instructions <deploy/production>`
+ * :doc:`Customizing look and feel of geonode <deploy/customize>`
+ * :doc:`Debugging problems <deploy/debug>`
+
+
+For Developers
+==============
+
+ * :doc:`Configuring GeoNode in development mode <developers/setup>`
+ * :doc:`Testing <developers/tests>`
+ * :doc:`Architecture Overview <developers/architecture>`
+ * :doc:`Extending GeoNode <developers/extend>`
+ * :doc:`Contributing to GeoNode <developers/contribute>`
+ * :doc:`Submitting patches <developers/patches>`
+ * :doc:`GeoNode Improvement Proposals - GNIP <developers/gnips>`
+ * :doc:`Reference documents <developers/reference/index>`
+
+Getting help
+============
+
+Having trouble? We'd like to help!
+
+ * Search for information in the `archives of the geonode mailing list`_, or
+ `post a question`_.
+
+ * Ask a question in the `#geonode IRC channel`_ using
+ `Freenode's web based client`_
+
+ * Report bugs with GeoNode in our `ticket tracker`_.
+
+.. _archives of the geonode mailing list: http://librelist.com/browser/geonode/
+.. _post a question: mailto:geonode@librelist.com
+.. _#geonode IRC channel: irc://irc.freenode.net/geonode
+.. _Freenode's web based client: http://webchat.freenode.net
+.. _ticket tracker: http://dev.geonode.org/trac
+
+.. toctree::
+ :hidden:
+ :maxdepth: 3
+
+ intro/overview
+ intro/install
+ users/register
+ users/upload
+ deploy/install
+
View
53 docs/intro/install.txt
@@ -0,0 +1,53 @@
+========================
+Quick installation guide
+========================
+
+The following is a quick guide to get GeoNode up and running in most common operating systems.
+
+Recommended Minimum System Requirements
+=======================================
+
+For deployment of GeoNode on a single server, the following are the bare minimum system requirements:
+
+* 6GB of RAM, including swap space.
+* 2.2GHz processor. (Additional processing power may be required for multiple concurrent styling renderings)
+* 1 GB software disk usage.
+* Additional disk space for any data hosted with GeoNode and tiles cached with GeoWebCache.
+ For spatial data, cached tiles, and "scratch space" useful for administration, a decent baseline size for GeoNode deployments is 100GB.
+* 64-bit hardware recommended.
+
+
+Linux
+=====
+
+Ubuntu
+------
+
+The easiest way to get the .deb is to install it using APT, the standard installation management tool for Ubuntu and other Debian-based systems.
+
+1) Set up the GeoNode PPA repository (you only need to do this once; the repository will still be available for upgrades later)::
+
+ sudo add-apt-repository ppa:geonode/release
+
+2) Install the package. This step will also automatically download any needed dependencies::
+
+ sudo apt-get update
+ sudo apt-get install geonode
+
+Once the package is installed, please consult the :doc:`/deploy/production` to learn how to create the admin user and tweak the settings to get more performance.
+
+CentOS/RHEL and other *nix distros
+-----------------------------------
+
+We recommend you to download the latest release and modify the included ``install.sh`` and ``support/config.sh``. GeoNode has been installed in CentOS/RHEL using this mechanism.
+
+Once the package is installed, please consult the :doc:`/deploy/production` to learn how to create the admin user and tweak the settings to get more performance.
+
+
+Windows, OSX and others
+=======================
+
+The recommended install method in these platforms is to use a virtualization solution, like `Virtual Box`_, install the latest `Ubuntu Linux`_ and then proceed with the steps mentioned above.
+