temporary removed part of the howto

source/howto/development.rst

@@ -3,21 +3,23 @@
 
 .. _development:
 
-How to set up a BDP locally
-===========================
+How to setup your local Development Environment
+===============================================
 
 This tutorial will guide you in the setup of the local infrastructure
-to be able to deploy a new Data Collector Object starting from a
-simple :strong:`HelloWorld` template we provide.
+to be able to deploy, on top of the Big Data Platform, a new Data
+Collector Object starting from a simple :strong:`HelloWorld` template
+we provide.
 
-This tutorial is divided into six parts:
+This tutorial is divided into three parts:
 
-#. Software Installation
-#. Application Server Setup
-#. Database Setup
-#. Repository setup   
+#. Software installation
+#. Services configuration
 #. Coding 
 
+.. warning:: This tutorial is still work in progress and is largely incomplete!
+
+
 Software Installation
 ---------------------
 
@@ -36,10 +38,12 @@ In this tutorial we are using a virtual machine with installed
 You need to install the following software:
 
 * PostgreSQL 9.3 or higher with postgis 2.2 extension.
-* JRE7 or higher (JRE8 suggested)
-* git version control system
-* Apache Maven\ :sup:`#`
-* An application server (tomcat8 suggested)\ :sup:`#`
+* JRE7 or higher (JRE8 suggested).
+* git version control system.
+* xmlstarlet to edit the XML configuration file - you will need to do
+  it manually otherwise.
+* Apache Maven\ :sup:`#`.
+* An application server (tomcat8 suggested)\ :sup:`#`.
 
   :sup:`#`\ These components are optional. You can skip Apache
   Maven installation if you do not use it and use the online
@@ -52,31 +56,24 @@ you have the rights to install software:
 
 .. code-block:: bash
 	  
-   odh@bdp:~$ sudo apt-get install git openjdk-8-jdk postgresql postgis maven tomcat8  
+   odh@bdp:~$ sudo apt-get install git openjdk-8-jdk postgresql postgis maven tomcat8 xmlstarlet 
 
 This command ensures that all dependencies are installed as well. If
 you have none of these package already installed, you might need to
 download ~125Mb of packages.
 
+Services configuration
+----------------------
 
+.. _setup-troubleshooting:
 
-Application Server Setup
-------------------------
-
-Once you installed tomcat, it should start immediately and listen on
-port :envvar:`8080` and also restart every time you reboot your
-workstation/server on which tomcat is installed. It requires no
-changes to the configuration files, as the vanilla installation
-suffices for our needs.
-
-You can find the log files of tomcat in the directory :file:`/var/log/tomcat8/catalina.out.`
-
-
-
-Application server testing & troubleshooting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Troubleshooting
+---------------
 
-You can check that tomcat is running by issuing the command
+You can check that tomcat is running either from the CLI or using a
+web browser. From the CLI you should issue the command ans see an
+output similar to the one show, where at the :green:`active
+(running)` string can be read.
 
 .. code-block:: bash
 
@@ -93,8 +90,16 @@ You can check that tomcat is running by issuing the command
    Jun 13 16:36:28 bdp tomcat8[13802]:    ...done.
    Jun 13 16:36:28 bdp systemd[1]: Started LSB: Start Tomcat..
 
-While from a browser you should connect to port 8080 and see the
-following page:
+If you do not use systemd, the command will have a differnt output:
+
+.. code-block:: bash
+
+   odh@bdp:~$ service tomcat8 status
+   [ ok ] Tomcat servlet engine is running with pid 11357.
+
+From a browser you should connect to http://localhost:8080/ (replace
+:envvar:`localhost` this the URL or IP where your application server
+is located) and see the following page:
 
 .. figure:: /images/tomcatOK.png
    :width: 80%
@@ -111,109 +116,4 @@ entering your password.
 
 You can check again if tomcat is running with the command
 :command:`service tomcat8 status`.
-
-
-Database Setup
---------------
-
-You should set up the database  as the :envvar:`postgres` user,
-therefore you need to become root and then postgres:
-
-.. code-block:: bash
-
-
-   odh@bdp:~$ sudo -i
-   [sudo] password for odh: 
-   root@bdp:~# su - postgres
-   postgres@bdp:~$ 
-
-Create a database called :strong:`acme` with two users:
-:strong:`acmeowner` and :strong:`acmeuser`.
-
-   createdb acme
-   createuser acmeowner
-   createuser acmeuser
-
-Assign to `acmeowner` full privile
-   psql acme
-   > alter database acme owner to acmeowner
-   > GRANT SELECT ON ALL TABLES IN SCHEMA intime TO acmeuser;
-   > GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA intime TO acmeuser;
-   > create extension postgis
-   psql -U acme acmeowner < schema.dump
-
-Lines 1-4 create the database :strong:`acme` and two users, 
-:strong:`acmeowner` who will be the db owner (line 5) and
-:strong:`acmeuser` who can access but not modify the DB (lines
-6-7).
-
-Line 8 adds the postgis extension to the :strong:`acme` database and
-finally line 9 imports the schema in the database.
-
-Repository Setup
-----------------
-
-Once the software is installed, you can proceed in setting up the
-repositories and configuring them to be used in the application
-server.
-
-There are two repositories to clone directly from github,
-:strong:`bdp-helloworld` and :strong:`bdp-core`. The former contains
-only a sample `Hello World` java class that can be used as a stub to
-build more complex projects, while the second one is the core
-infrastructure of the |odh|.
-
-.. code-block:: bash
-   
-   odh@bdp:~$ mkdir ODH
-   odh@bdp:~$ cd ODH
-   odh@bdp:~$ git clone https://github.com/idm-suedtirol/bdp-core.git
-   odh@bdp:~$ git clone https://github.com/idm-suedtirol/bdp-helloworld.git
-   odh@bdp:~$ ls -l
-   total 8
-   drwxrwxr-x 9 odh odh 4096 Jun 13 17:39 bdp-core
-   drwxrwxr-x 4 odh odh 4096 Jun 13 17:39 bdp-helloworld
 
-Code setup
-~~~~~~~~~~
-
-Now, compile the code to be able to use it in the application server.
-
-.. code-block:: bash
-
-   odh@bdp:~$ bdp-core
-   odh@bdp:~$ cd dto
-   odh@bdp:~$ mvn install
-   odh@bdp:~$ cd ../dal
-   odh@bdp:~$ vim src/main/resources/META-INF/persistence.xml
-   odh@bdp:~$ mvn clean install
-   odh@bdp:~$ cd ../writer
-   odh@bdp:~$ mvn clean package
-   odh@bdp:~$ cd ../reader
-   odh@bdp:~$ mvn clean package
-   odh@bdp:~$ cd ..
-   odh@bdp:~$ mv writer/writer.war ${APPLICATION_SERVER_HOME}
-   odh@bdp:~$ mv reader/reader.war ${APPLICATION_SERVER_HOME}
-   
-.. todo:: How should :strong:`persistence.xml` (line 7) be edited?
-
-The local setup of bdp-core is completed by adding the project to
-maven, for an easier management of the project, and by building the
-:strong:`writer.war` and :strong:`reader.war` files, that will be then
-moved to the application server (lines 3-15).
-
-
-To verify that the .war files have been deployed correctly, go to the
-links http\://{host}:{port}/writer/json and
-http\://{host}:{port}/reader/json: you must receive a :strong:`405 GET
-method not allowed` error. 
-
-
-
-Coding
-------
-
-
-.. todo:: Once you are done with the set up, you can have a look at
-   our :strong:`HelloWorld` example and start the development from
-   there.