documentation update

doc/dev_setup.md

+
+## dev overview
+
+comex app contains:
+  - several php files specialized in retrieving custom lists of scholars, labs, jobs for directory showing
+    - `whoswho.js` is used to GUIise the queries
+    - legacy jquery and highcharts are used to GUIise the directories
+  - a python server for the app's services
+    - the services views are in `services/main.py`
+    - the main templates are `base_layout.html` and `rootindex.html`
+    - main and `services/user.py` handle DB add/modify/remove scholars
+    - `services/db_to_tina_api` contains a custom python extraction function for tinawebJS
+  - a copy of tinawebJS in `static/tinawebJS` to explore the data in graph view
+    - the twjs is in a legacy version, downloadable [via this subtree](https://github.com/moma/tinawebJS/tree/comex_wip)
+
+-------
+
+### Running in dev
+
+In development, it is more natural to run the app *without* the docker wrapper.
+This way one can see the effects of changes without the bother of committing them, pulling them in the image and rebuilding the image.
+
+Another difference is that without the docker wrapper, the app will be available on COMEX_HOST:9090 instead of 8080.
+
+#### Minimal config
+
+```
+# get the code
+git clone https://github.com/moma/comex2
+
+# get prerequisites
+sudo apt install php7.0-fpm php7.0-mysql python3 libmysqlclient-dev
+cd $INSTALL_DIR
+sudo pip3 install -r setup/requirements.txt
+```
+
+Then to run the comex2 services in the simplest way just do:
+```
+cd services
+python3 comex_main_backend.py
+```
+The form server is then accessible locally on `0.0.0.0:5000/services/user`
+The tina api server is on `0.0.0.0:5000/services/api`
+
+Check the parameters in `config/parametres_comex.ini`
+
+Finally, simply configure the serving of your php|www documentroot in nginx (cf [detailed doc](https://github.com/moma/comex2/blob/master/doc/nginx_conf.md) for real-life conf).
+
+
+-------
+
+#### Advanced dev config
+  1. external mysql database
+  2. external doors (or simulated by docker)
+  3. gunicorn webserver (linked to 1 & 2 via `$SQL_HOST` and `$DOORS_HOST`)
+
+##### 1) Set up your mysql database
+
+###### If you have your own local mysql
+```
+# edit ini file to put the correct SQL_HOST (or IP)
+nano config/parametres_comex.ini
+```
+Then just create the table following [the table specifications](https://github.com/moma/comex2/blob/master/doc/table_specifications.md)
+
+###### If you want a dedicated mysql in docker
+
+  - Follow the detailed steps in [mysql_prerequisites](https://github.com/moma/comex2/blob/master/setup/dockers/mysql_prerequisites.md): it will explain how to create the docker and connect to it.
+
+  - Then create the table following [the table specifications](https://github.com/moma/comex2/blob/master/doc/table_specifications.md)
+  - Now run it as follows:
+
+```
+# run the database docker
+docker start comex_db
+
+# read its IP
+docker inspect comex_db | jq -r '.[0].NetworkSettings.IPAddress'
+
+# edit ini file to put it as SQL_HOST
+nano config/parametres_comex.ini
+```
+
+##### 2) Set up a doors connection
+Again, the environment variable `DOORS_HOST` must simply be set to the doors server's hostname or IP, and `DOORS_PORT` to the doors server's exposed port.
+
+###### If you have a doors server
+```
+# edit ini file to put it as DOORS_HOST and DOORS_PORT
+nano config/parametres_comex.ini
+```
+
+###### If you have no doors server
+
+For tests you can use a `minidoors` container
+```
+# build the docker image (once)
+cd setup/dockers
+docker build -t minidoors:latest minidoors/
+
+# run the container (each time)
+docker run -it -p 32789:8989 --name doors_test minidoors
+```
+
+##### 3) Run the regomex app with gunicorn
+```
+bash comex-run.sh
+```
+
+The form server is then accessible locally on `0.0.0.0:9090/services/user/register`
+
+**Remark:** the prefix `/services` and the user route `/user` can both be changed in the config file
+
+-------

doc/nginx_conf.md

@@ -34,20 +34,27 @@ This below is a full config exemple you can paste in nano:
 server {
     listen 80 ;
     listen [::]:80 ;
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    # SSL certificates
+        # self-signed certificates
+        include snippets/snakeoil.conf;
 
-    # server_name communityexplorer.org;
-    server_name _ ;
+        # uncomment if certificates for https://your-domain.org
+        # ssl_certificate /etc/ssl/cert/ssl-for_your_domain.pem;
+        # ssl_certificate_key /etc/ssl/private/ssl-for_your_domain.key;
+
+    # server_name your-domain.org;
 
     # get the logs in a custom place
     # (adapt paths)
-    access_log /home/romain/comex/outer_nginx_access.log ;
-    error_log /home/romain/comex/outer_nginx_error.log ;
+    access_log /home/somewhere/outer_nginx_access.log ;
+    error_log /home/somewhere/outer_nginx_error.log ;
 
-    # independant app with its own nginx serving:
+    # proxy pointing to the docker app with its own inner nginx serving:
     #     the php root on '/'
     #     the python server on 'services/'
     location / {
-        # pointing to the local bridge to the dockerized nginx serving all comex2 parts
         proxy_pass http://0.0.0.0:8080;
         proxy_redirect     off;
 
@@ -58,6 +65,10 @@ server {
         proxy_set_header   X-Forwarded-Host $server_name;
     }
 
+    # faster shortcut to static files w/o docker
+    location /static {
+        alias  /path/to/your/install/of/comex2/static;
+    }
 }
 ```
 

setup/comex2_deployed_outer.nginx.conf

@@ -35,15 +35,6 @@ server {
         proxy_set_header   X-Forwarded-Host $server_name;
     }
 
-    # for minidoors api
-    location /api {
-        proxy_pass http://0.0.0.0:32789;
-        proxy_redirect     off;
-        proxy_set_header   Host $host;
-        proxy_set_header   X-Real-IP $remote_addr;
-        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header   X-Forwarded-Host $server_name;
-    }
     # faster shortcut to static files w/o docker
     location /static {
         alias  /home/ubuntu/active_webapps/comex2/static;