.. _installation: Installation ============ System Requirements ------------------- pycsw is written in `Python `_, and works with (tested) version 2.6, 2.7 and 3.4 pycsw requires the following Python supporting libraries: - `lxml`_ for XML support - `SQLAlchemy`_ for database bindings - `pyproj`_ for coordinate transformations - `Shapely`_ for spatial query / geometry support - `OWSLib`_ for CSW client and metadata parser - `six`_ for Python 2/3 compatibility - `xmltodict`_ for working with XML similar to working with JSON - `geolinks`_ for dealing with geospatial links .. note:: You can install these dependencies via `easy_install`_ or `pip`_ .. note:: For :ref:`GeoNode ` or :ref:`Open Data Catalog ` or :ref:`HHypermap ` deployments, SQLAlchemy is not required Installing from Source ---------------------- `Download `_ the latest stable version or fetch from Git. For Developers and the Truly Impatient ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The 4 minute install: .. code-block:: bash $ virtualenv pycsw && cd pycsw && . bin/activate $ git clone https://github.com/geopython/pycsw.git && cd pycsw $ pip install -e . && pip install -r requirements-standalone.txt $ cp default-sample.cfg default.cfg $ vi default.cfg # adjust paths in # - server.home # - repository.database # set server.url to http://localhost:8000/ $ python pycsw/wsgi.py $ curl http://localhost:8000/?service=CSW&version=2.0.2&request=GetCapabilities The Quick and Dirty Way ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash $ git clone git://github.com/geopython/pycsw.git Ensure that CGI is enabled for the install directory. For example, on Apache, if pycsw is installed in ``/srv/www/htdocs/pycsw`` (where the URL will be ``http://host/pycsw/csw.py``), add the following to ``httpd.conf``: .. code-block:: none Options +FollowSymLinks +ExecCGI Allow from all AddHandler cgi-script .py .. note:: If pycsw is installed in ``cgi-bin``, this should work as expected. In this case, the :ref:`tests ` application must be moved to a different location to serve static HTML documents. Make sure, you have all the dependencies from ``requirements.txt and requirements-standalone.txt`` The Clean and Proper Way ^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash $ git clone git://github.com/geopython/pycsw.git $ python setup.py build $ python setup.py install At this point, pycsw is installed as a library and requires a CGI ``csw.py`` or WSGI ``pycsw/wsgi.py`` script to be served into your web server environment (see below for WSGI configuration/deployment). .. _pypi: Installing from the Python Package Index (PyPi) ----------------------------------------------- .. code-block:: bash # easy_install or pip will do the trick $ easy_install pycsw # or $ pip install pycsw .. _opensuse: Installing from OpenSUSE Build Service -------------------------------------- In order to install the pycsw package in openSUSE Leap (stable distribution), one can run the following commands as user ``root``: .. code-block:: bash # zypper -ar http://download.opensuse.org/repositories/Application:/Geo/openSUSE_Leap_42.1/ GEO # zypper refresh # zypper install python-pycsw pycsw-cgi In order to install the pycsw package in openSUSE Tumbleweed (rolling distribution), one can run the following commands as user ``root``: .. code-block:: bash # zypper -ar http://download.opensuse.org/repositories/Application:/Geo/openSUSE_Tumbleweed/ GEO # zypper refresh # zypper install python-pycsw pycsw-cgi An alternative method is to use the `One-Click Installer `_. .. _ubuntu: Installing on Ubuntu/Mint ------------------------- In order to install the most recent pycsw release to an Ubuntu-based distribution, one can use the UbuntuGIS Unstable repository by running the following commands: .. code-block:: bash # sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable # sudo apt-get update # sudo apt-get install python-pycsw pycsw-cgi Alternatively, one can use the UbuntuGIS Stable repository which includes older but very well tested versions: # sudo add-apt-repository ppa:ubuntugis/ppa # sudo apt-get update # sudo apt-get install python-pycsw pycsw-cgi .. note:: Since Ubuntu 16.04 LTS Xenial release, pycsw is included by default in the official Multiverse repository. Running on Windows ------------------ For Windows installs, change the first line of ``csw.py`` to: .. code-block:: python #!/Python27/python -u .. note:: The use of ``-u`` is required to properly output gzip-compressed responses. Security -------- By default, ``default.cfg`` is at the root of the pycsw install. If pycsw is setup outside an HTTP server's ``cgi-bin`` area, this file could be read. The following options protect the configuration: - move ``default.cfg`` to a non HTTP accessible area, and modify ``csw.py`` to point to the updated location - configure web server to deny access to the configuration. For example, in Apache, add the following to ``httpd.conf``: .. code-block:: none order allow,deny deny from all Running on WSGI --------------- pycsw supports the `Web Server Gateway Interface`_ (WSGI). To run pycsw in WSGI mode, use ``pycsw/wsgi.py`` in your WSGI server environment. .. note:: ``mod_wsgi`` supports only the version of python it was compiled with. If the target server already supports WSGI applications, pycsw will need to use the same python version. `WSGIDaemonProcess`_ provides a ``python-path`` directive that may allow a virtualenv created from the python version ``mod_wsgi`` uses. Below is an example of configuring with Apache: .. code-block:: none WSGIDaemonProcess host1 home=/var/www/pycsw processes=2 WSGIProcessGroup host1 WSGIScriptAlias /pycsw-wsgi /var/www/pycsw/wsgi.py Order deny,allow Allow from all or use the `WSGI reference implementation`_: .. code-block:: bash $ python ./pycsw/wsgi.py Serving on port 8000... which will publish pycsw to ``http://localhost:8000/`` .. _`lxml`: http://lxml.de/ .. _`SQLAlchemy`: http://www.sqlalchemy.org/ .. _`Shapely`: http://toblerity.github.io/shapely/ .. _`pyproj`: http://code.google.com/p/pyproj/ .. _`OWSLib`: https://github.com/geopython/OWSLib .. _`six`: https://pypi.python.org/pypi/six/ .. _`xmltodict`: https://github.com/martinblech/xmltodict .. _`geolinks`: https://github.com/geopython/geolinks .. _`easy_install`: http://packages.python.org/distribute/easy_install.html .. _`pip`: http://www.pip-installer.org .. _`Web Server Gateway Interface`: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface .. _`WSGIDaemonProcess`: https://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIDaemonProcess .. _`WSGI reference implementation`: http://docs.python.org/library/wsgiref.html