Merge pull request #23 from tracim/fix/better_readme

README.md

@@ -3,6 +3,7 @@ develop branch status:
 [![Coverage Status](https://coveralls.io/repos/github/tracim/tracim_v2/badge.svg?branch=develop)](https://coveralls.io/github/tracim/tracim_v2?branch=develop)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/tracim/tracim_v2/badges/quality-score.png?b=develop)](https://scrutinizer-ci.com/g/tracim/tracim_v2/?branch=develop)
 
+
 ## Install Tracim on your server ##
 
 Following the installation documentation below, you'll be able to run your own instance on your server.
@@ -13,30 +14,40 @@ Following the installation documentation below, you'll be able to run your own i
 
 ## Get the source ##
 
-Get the sources from GitHub:
+Get the sources from GitHub (you need git):
 
     git clone https://github.com/tracim/tracim_v2.git
     cd tracim_v2/
 
-## Install backend ##
+## Install backend
+### Option 1: Install backend manually ###
+
+see [Backend README](backend/README.md)
+
+### Option2: Install backend: Automated script for easy setup ###
+
+This script run backend with simple default conf: development.ini conf file, use
+default config file, sqlite database, etc...
 
     ./setup_default_backend.sh
 
-For debugging you can uncomment this 2 lines in '/backend/development.ini'
-    
-    ~~~
-    #pyramid.includes =
-    #    pyramid_debugtoolbar
-    ~~~
+For each conf file missing, this script will generated them from default conf.
+If sqlite default database is missing, script will generate it.
+This script is also able to serve for update. If you want to update a script
+generated tracim install, you can just update source code with git pull and
+rerun the same script to update database model, system deps and python deps.
+
+for more information about configuring tracim_backend, see [Backend README](backend/README.md)
+for more information about configuration file, see development.ini.sample documentation
+and [Backend setting file doc](backend/doc/setting.md).
 
-If you use debugtoolbar, you can seen one red button on right of the Tracim web interface.
 
-## Install frontend ##
+## Install frontend: Automated Script for easy setup ##
 
     ./install_frontend_dependencies.sh
     ./build_full_frontend.sh
 
-## Running Tracim  ##
+## Running Tracim using pserve ##
 
     cd backend/
     source env/bin/activate
@@ -45,7 +56,7 @@ If you use debugtoolbar, you can seen one red button on right of the Tracim web
 You can now enter the application at
 [http://127.0.0.1:6543](http://127.0.0.1:6543) and login with admin user:
 
- * user : `admin@admin.admin`
- * password : `admin@admin.admin`
+ * user: `admin@admin.admin`
+ * password: `admin@admin.admin`
 
 

backend/doc/setting.md

@@ -1,8 +1,13 @@
-# Setting #
+# Settings #
 
-Here is a short description of settings available in the file `development.ini`.
+Here is a short description of settings available in backend config files.
 
-## Listening port ##
+# Tracim config ini file #
+
+This file is called'development.ini' file by default, it's located is backend
+subdir, default config is [development.ini.sample](../development.ini.sample) with some doc.
+
+## Listening port (for pserve only) ##
 
 Default configuration is to listen on port 6534.
 If you want to adapt this to your environment, edit the `.ini` file and setup the port you want:
@@ -17,30 +22,93 @@ To allow other computer to access to this website, listen to "*" instead of loca
     ...
     listen = *:6534
 
-## Prod/Debug configuration ##
+## Database path ##
+
+To configure a database, you need to provide a valid sqlalchemy url:
+
+for sqlite, a valid value is something like this:
+
+    sqlalchemy.url = sqlite:///%(here)s/tracim.sqlite
+
+to know more about this, see [sqlalchemy documentation](http://docs.sqlalchemy.org/en/latest/core/engines.html).
+
+Be carefull, if sqlalchemy support many kind of Database, Tracim support is **not** guarantee.
+Tracim is officially supporting sqlite, postgresql and mysql.
+
+## Debugging and Logs ##
+### Debug params ###
+
+
+For debugging you can uncomment this 2 lines in '/backend/development.ini' to
+enable pyramid debugtoolbar.
+If you use debugtoolbar, you can seen one red button on right of the Tracim web interface.
+
+    ~~~
+    #pyramid.includes =
+    #    pyramid_debugtoolbar
+    ~~~
+
+you can add this line to active pyramid debug mode for almost anything:
+
+    ~~~
+    pyramid.debug_all = true
+    ~~~
+
+
+Hapic debug mode: this line is needed for more explicit json error,
+raised error traceback will be send through json. you can uncomment it
+
+   ~~~
+   # debug = True
+   ~~~
+
+pyramid.reload_templates = true
+
+### Prod/Debug configuration example ###
 
 
 To enable simple debug conf:
 
-    [app:main]
+    [app:tracim_web]
     ...
     pyramid.reload_templates = true
     pyramid.debug_all = true
     pyramid.includes =
         pyramid_debugtoolbar
 
+    [DEFAULT]
+    ...
+    debug = True
+
+
 production conf (no reload, no debugtoolbar):
 
-    [app:main]
+    [app:tracim_web]
     ...
     pyramid.reload_templates = false
     pyramid.debug_authorization = false
     pyramid.debug_notfound = false
     pyramid.debug_routematch = false
 
-You can, of course, also set level of one of the different logger to have more/less log
-about something.
+    [DEFAULT]
+    ...
+    debug = False
+
+You can, of course, also set level of one of the different logger
+to have more/less log about something.
 
     [logger_sqlalchemy]
     ...
     level = INFO
+
+# Color File #
+
+You can change default color of apps by setting color.json file, by default,
+placed at root of tracim_v2 dir, see [color.json.sample](../../color.json.sample)
+for default config file.
+
+# Wsgidav File
+
+This file is by default placed in backend subdir,
+it by default called wsigdav.conf, for more information, see default
+conf file [wsigdav.conf.sample](../wsgidav.conf.sample).