web admin and process control

.gitignore

@@ -1,6 +1,7 @@
 *.pyc
 *.pyo
 *.egg-info
+*.idea
 dist
 build
 tmp

docs/api.rst

@@ -26,6 +26,8 @@ Defining processes
 Request and response objects
 ----------------------------
 
+.. module:: pywps.app
+
 .. autoclass:: WPSRequest
    :members:
 

docs/index.rst

@@ -21,6 +21,7 @@ Contents:
    :maxdepth: 2
 
    install
+   rest_api
    configuration
    process
    exceptions

docs/install.rst

@@ -2,6 +2,7 @@
 PyWPS-4 Installation
 ====================
 
+.. note:: This installation documentation was tested on the Ubuntu 14.04 LTS operating system.
 
 .. note:: PyWPS-4 is not tested on MS Windows platform. Please join the
     development, if you need this platform to be supported. It's mainly because
@@ -11,52 +12,201 @@ PyWPS-4 Installation
 
 
 Dependencies
-~~~~~~~~~~~~
+============
 
-PyWPS-4 runs on Python 2.7, 3.3 or newer.
+In the command line::
 
-Prior to installing PyWPS-4, Git and the Python bindings for GDAL must be installed in the system. 
-In Debian based systems these packages can be installed with a tool like *apt*::
+    $ sudo apt-get install git python-gdal python-pip python-dev libxml2-dev libxslt1-dev zlib1g-dev libpq-dev apache2 libapache2-mod-wsgi postgresql postgresql-contrib
+    $ sudo pip install virtualenv
 
-    $ sudo apt-get install git python-gdal
 
+Installation
+============
 
-PyWPS-4
-~~~~~~~
+A standard installation is standard Python package installation. If you want to contribute or work on PyWPS, the installation in the develop mode is also described and differs in a detail.
 
-The easiest way to install PyWPS-4 is using the Python Package Index (PIP). 
-It fetches the source code from the repository and installs it automatically in the system.
-This might require superuser permissions (e.g. *sudo* in Debian based systems)::
+Normal installation
+-------------------
 
-    $ sudo pip install -e git+https://github.com/pywps/pywps-4.git@master#egg=pywps-dev
+In the command line::
 
-In alternative PyWPS-4 can be installed manually.
-It requires the cloning of the source code from the repository and then the usage of the *setup.py* script.
-An example again for Debian based systems (note the usage of *sudo* for install)::
+    $ sudo virtualenv /var/www/gsoc-pywps-env
+    $ cd /var/www/gsoc-pywps-env
+    $ source bin/activate
 
-    $ git clone https://github.com/pywps/pywps-4.git
+Change ownership and group permission according to your user account, replace the string user with your username (replace ``<user>`` with your username)::
 
-    $ cd pywps-4/
+    $ sudo chown -R <user>:<user> /var/www/gsoc-pywps-env
 
-Then install deps using pip::
+Clone the PyWPS and the example application into the activated virtual enviroment::
 
+    $ git clone https://github.com/jan-rudolf/pywps
+    $ git clone https://github.com/jan-rudolf/gsoc-pywps-app
+
+Install Python packages and install the PyWPS::
+
+    $ cd pywps
+    $ pip install -r requirements.txt
+    $ python setup.py install
+
+Create **/tmp/outputs** directory and change group and owner to the user that runs the application, for Apache the username and the groupname would be **www-data** by default::
+
+    $ sudo mkdir /tmp/outputs
+    $ sudo chown <username>:<groupname> /tmp/outputs
+
+
+Develop installation
+--------------------
+
+In the command lineIn the command line::
+
+    $ sudo virtualenv /var/www/gsoc-pywps-env
+    $ cd /var/www/gsoc-pywps-env
+    $ source bin/activate
+
+Change ownership and group permission according to your user account, replace the string user with your username (replace ``<user>`` with your username)::
+
+    $ sudo chown -R <user>:<user> /var/www/gsoc-pywps-env
+
+Clone the PyWPS and the example application into the activated virtual enviroment::
+
+    $ git clone https://github.com/jan-rudolf/pywps
+    $ git clone https://github.com/jan-rudolf/gsoc-pywps-app
+
+Install Python packages and install the PyWPS::
+
+    $ cd pywps
     $ pip install -r requirements.txt
-    $ pip install -r requirements-dev.txt  # for developer tasks
+    $ python setup.py develop
+
+Create **/tmp/outputs** directory and change group and owner to the user that runs the application, for Apache the username and the groupname would be **www-data** by default::
+
+    $ sudo mkdir /tmp/outputs
+    $ sudo chown <username>:<groupname> /tmp/outputs
+
+
+Database
+========
+
+This section describes how to setup and connect SQLite and PostgreSQL with the PyWPS. 
+
+More about how to connect other engines in the `SQLAlchemy Documentation <http://docs.sqlalchemy.org/en/latest/core/engines.html>`_.
+
+
+SQLite
+------
+
+Change the **SQLAlchemyDatabaseUri** in the PyWPS configuration file under the **server** section::
+
+   SQLAlchemyDatabaseUri=sqlite:////absolute/path/to/<database_name>
+
+Create database tables by the GET HTTP request to::
+
+   http://<URL_address>/create-database-tables
+
+
+PostgreSQL
+----------
+
+System configuration
+~~~~~~~~~~~~~~~~~~~~
+
+In the command line, switch to the postgres user::
+
+   $ sudo su postgres
+
+Create a user for the database system, fill your username::
+
+   $ createuser --pwprompt <username>
+
+Create a database with the utf-8 encoding, fill your username from the previous step and the desired database name::
+
+   $ createdb -O<username> -Eutf-8 <database_name>
+
+Exit the postgres's user prompt::
+
+   $ exit
+
+Edit the table (near end of the file), that looks like the one below, so that the **METHOD** column has only **md5** entries (in case you have a different version of PostgreSQL, edit the path to the file with proper version)::
+
+   $ sudo $EDITOR /etc/postgresql/9.3/main/pg_hba.conf
+
++------------+------------+-----------+--------------+---------+ 
+| TYPE       | DATABASE   | USER      | ADDRESS      | METHOD  |
++============+============+===========+==============+=========+
+| local      | all        | all       |              | peer    |
++------------+------------+-----------+--------------+---------+
+| host       | all        | all       | 127.0.0.1/32 | md5     |
++------------+------------+-----------+--------------+---------+
+| host       | all        | all       | ::1/128      | md5     |
++------------+------------+-----------+--------------+---------+ 
+
+Restart the PostgreSQL service::
+
+   $ sudo service postgresql restart
+
+
+PyWPS's configuration file setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Change the **SQLAlchemyDatabaseUri** in the PyWPS configuration file under the **server** section::
+
+   SQLAlchemyDatabaseUri=postgresql://<username>@localhost/<database_name>?sslmode=disable
+
+*Note:* I added the parameter ``sslmode=disable``, because without it it causes error and exceptions somehow randomly. I have not figured out why.
+
+
+Apache
+======
+
+In the case you want to server PyWPS on the Apache web server, here is an example of the virtual host configuration file. All paths and names are according the Installation subsection.  
+
+.. code::
+
+    <VirtualHost *:80>
+        # The ServerName directive sets the request scheme, hostname and port that
+        # the server uses to identify itself. This is used when creating
+        # redirection URLs. In the context of virtual hosts, the ServerName
+        # specifies what hostname must appear in the request's Host: header to
+        # match this virtual host. For the default virtual host (this file) this
+        # value is not decisive as it is used as a last resort host regardless.
+        # However, you must set it for any further virtual host explicitly.
+        ServerName pywps.loc
+        ServerAlias www.pywps.loc
+
+        ServerAdmin webmaster@localhost
+        #DocumentRoot /var/www/html
+
+        # Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
+        # error, crit, alert, emerg.
+        # It is also possible to configure the loglevel for particular
+        # modules, e.g.
+        #LogLevel info ssl:warn
+
+        ErrorLog ${APACHE_LOG_DIR}/error.log
+        CustomLog ${APACHE_LOG_DIR}/access.log combined
 
-And install PyWPS system-wide::
+        # For most configuration files from conf-available/, which are
+        # enabled or disabled at a global level, it is possible to
+        # include a line for only one particular virtual host. For example the
+        # following line enables the CGI configuration for this host only
+        # after it has been globally disabled with "a2disconf".
+        #Include conf-available/serve-cgi-bin.conf
 
-    $ sudo python setup.py install
+        WSGIProcessGroup pywps.loc
+        WSGIDaemonProcess pywps.loc processes=2 threads=15 display-name=%{GROUP} 
+        WSGIScriptAlias / /var/www/gsoc-pywps-env/gsoc-pywps-app/wsgi.py
 
-The demo service
-~~~~~~~~~~~~~~~~
+        Alias "/outputs" "/tmp/outputs/"
+        <Directory "/tmp/outputs">
+            Require all granted
+        </Directory>
 
-To use PyWPS-4 the user must code processes and publish them through a service.
-A demo service is available that makes up a good starting point for first time users.
-It can be cloned directly into the user area:
+        <Directory /var/www/gsoc-pywps-env/gsoc-pywps-app>
+            Order allow,deny
+            Allow from all 
+        </Directory> 
+    </VirtualHost>
 
-    $ git clone https://github.com/pywps/pywps-4-demo.git
 
-It may be run right away through the *demo.py* script. 
-First time users should start by studying the demo project structure and then code their own processes.
 
-Full more details please consult the :ref:`process` section.

docs/rest_api.rst

@@ -0,0 +1,96 @@
+========
+REST API
+========
+
+Processes published in PyWPS instance.
+
+/processes
+==========
+
+Lists running processes.
+
++--------+-----------------------------------------+----------+--------------+------------+
+| Method | Action                                  | Format   | Status Code  | Returns    |
++========+=========================================+==========+==============+============+
+| GET    | Returns a list of running processes     | JSON     | 200          | processes  |
++--------+-----------------------------------------+----------+--------------+------------+
+| POST   |                                         |          | 405          |            |
++--------+-----------------------------------------+----------+--------------+------------+
+| PUT    |                                         |          | 405          |            |
++--------+-----------------------------------------+----------+--------------+------------+
+| DELETE |                                         |          | 405          |            |
++--------+-----------------------------------------+----------+--------------+------------+
+
+Returns
+-------
+
+**processes**
+    Returns a list of running processes, every process is represented by *uuid*.
+
+
+/processes/<uuid>
+=================
+
+Controls a running process.
+
++--------+--------------------------------------------+----------+--------------+------------+---------------------------------+
+| Method | Action                                     | Format   | Status Code  | Parameters | Returns                         |
++========+============================================+==========+==============+============+=================================+
+| GET    | Returns a message (description) and status | JSON     | 200          |            | error, message, success, status |
++--------+--------------------------------------------+----------+--------------+------------+---------------------------------+
+| POST   | Returns a running description and status   | JSON     | 405          |            | error, status                   |
++--------+--------------------------------------------+----------+--------------+------------+---------------------------------+
+| PUT    | Manipulates a running process              | JSON     | 200          | action     | error, status                   |
++--------+--------------------------------------------+----------+--------------+------------+---------------------------------+
+| DELETE | Stop a running process                     | JSON     | 200          |            | error, status                   |
++--------+--------------------------------------------+----------+--------------+------------+---------------------------------+
+
+Parameters
+----------
+
+**action**
+    Specifies what action would you like a process to perform.
+
+    Options:
+        **pause** - Pause a running process.
+
+        **resume** - Resume a paused process.
+
+Returns
+-------
+
+**message**:
+    The last message/status provided by a process. These messages are designed by creators of processes scripts.
+
+**error**:
+    Describes why was the request unsuccessful. The *error* field is provided only if the *status* field has a value *false*.
+
+**success**:
+    Describes if the request was successful or not.
+
+    Options:
+        **true** - A successfully served request.
+
+        **false** - Unsuccessfully served request. An *error* message is also returned with this type of response.
+
+**status**:
+    Describes what is the status of the process.
+
+    Options:
+        **0** - NO STATUS
+
+        **1** - STORE STATUS
+
+        **2** - STORE AND UPDATE STATUS
+
+        **3** - DONE STATUS
+
+        **4** - PAUSED STATUS
+
+        **5** - STOPPED STATUS
+
+Example
+-------
+
+*http://localhost/wps/processes/slakdfj-234-ASDF-234* with PUT request ``{"action": "pause"}`` returns ``{"success": "true"}``
+