Streamline installation doc, now using pip (#252)

* Fix conf files to reflect module renaming

Python module was renamed budget → ihatemoney (see #243 and 6923367).
Now, "budget" relates to nothing.

* Harmonize `APPLICATION_ROOT` doc with other settings

* Fix link markup

* Switch documentation to recomend pip over git

- Update installation instruction
- Clearly separate dev setup from installation
- Some rewordings/section-ization by the way

* Add a hint on how to find the static path

This is a downside on the pip choice over git for installation.

We will have to ease that a bit. By doc or by code, before next release.

* Make the nginx deployment doc more accurate

* Add a big fat warning about SECRET_KEY in doc

conf/apache-vhost.conf

@@ -2,8 +2,8 @@
     ServerAdmin admin@example.com
     ServerName ihatemoney.example.com
     # Uncomment the python-home option if you use a virtualenv
-    WSGIDaemonProcess ihatemoney user=www-data group=www-data threads=5 python-path=/path/to/ihatemoney/budget # python-home=/path/to/your/venv
-    WSGIScriptAlias / /path/to/ihatemoney/budget/wsgi.py
+    WSGIDaemonProcess ihatemoney user=www-data group=www-data threads=5 python-path=/path/to/ihatemoney/ihatemoney # python-home=/path/to/your/venv
+    WSGIScriptAlias / /path/to/ihatemoney/ihatemoney/wsgi.py
     ErrorLog /var/log/apache2/ihatemoney.example.com_error.log
     CustomLog /var/log/apache2/ihatemoney.example.com_access.log combined
 <Directory /path/to/ihatemoney>
@@ -12,5 +12,7 @@
     Order deny,allow
     Allow from all
 </Directory>
-Alias /static/ /path/to/ihatemoney/budget/static/
+# Alias value may be some messy path, within python libs.
+# You may want to use "find $VIRTUAL_ENV -path */ihatemoney*/static" to find it.
+Alias /static/ /path/to/ihatemoney/ihatemoney/static/
 </VirtualHost>

conf/gunicorn.conf.py

@@ -2,6 +2,6 @@ backlog = 2048
 daemon = False
 debug = True
 workers = 3
-logfile = "/path/to/your/app/budget.gunicorn.log"
+logfile = "/path/to/your/app/ihatemoney.gunicorn.log"
 loglevel = "info"
-bind = "unix:/path/to/your/app/budget.gunicorn.sock"
+bind = "unix:/path/to/your/app/ihatemoney.gunicorn.sock"

conf/nginx.conf

@@ -3,7 +3,9 @@ server {
     keepalive_timeout 5;
 
     location /static/ {
-        alias   /path/to/app/budget/static/;
+        # Alias value may be some messy path, within python libs.
+        # You may want to use "find $VIRTUAL_ENV -path */ihatemoney*/static" to find it.
+        alias   /path/to/app/ihatemoney/static/;
     }
     location / {
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -17,12 +19,12 @@ server {
         proxy_busy_buffers_size 32k;
         proxy_intercept_errors on;
         if (!-f $request_filename) {
-            proxy_pass http://budget_backend;
+            proxy_pass http://ihatemoney_backend;
             break;
         }
     }
 }
 
-upstream budget_backend {
-        server unix:/path/to/app/budget.gunicorn.sock;
+upstream ihatemoney_backend {
+        server unix:/path/to/app/ihatemoney.gunicorn.sock;
 }

conf/supervisord.conf

@@ -1,6 +1,5 @@
 [program:budget]
-command=/path/to/your/app/venv/bin/gunicorn -c /path/to/your/app/conf/gunicorn.conf.py wsgi:application
-directory=/path/to/your/app/budget/
+command=/path/to/your/app/venv/bin/gunicorn -c /etc/ihatemoney/gunicorn.conf.py ihatemoney.wsgi:application
 user=www
 autostart=true
 autorestart=true

docs/contributing.rst

@@ -4,6 +4,52 @@ Contributing
 Setup a dev environment
 =======================
 
+You must develop on top of the git master branch::
+
+  git clone https://github.com/spiral-project/ihatemoney.git
+
+Then you need to build your dev environments. Choose your way…
+
+The quick way
+-------------
+
+If System :ref:`installation-requirements` are fulfilled, you can just issue::
+
+    make serve
+
+It will setup a `virtualenv <https://pypi.python.org/pypi/virtualenv>`_,
+install dependencies, and run the test server.
+
+The hard way
+------------
+
+Alternatively, you can also use the `requirements.txt` file to install the
+dependencies yourself. That would be::
+
+     pip install -r requirements.txt
+
+And then run the application::
+
+    cd ihatemoney
+    python run.py
+
+Accessing dev server
+--------------------
+
+In any case, you can point your browser at `http://localhost:5000 <http://localhost:5000>`_.
+It's as simple as that!
+
+
+Updating
+--------
+
+In case you want to update to newer versions (from git), you can just run the "update" command::
+
+  make update
+
+Useful settings
+----------------
+
 It is better to actually turn the debugging mode on when you're developing.
 You can create a ``settings.cfg`` file, with the following content::
 
@@ -47,7 +93,7 @@ End-user
 --------
 
 You are using the application and found a bug? You have some ideas about how to
-improve the project? Please tell us [by filling a new issue](https://github.com/spiral-project/ihatemoney/issues).
+improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_.
 Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I will
 update the issue tracker with your feedback.
 

docs/installation.rst

@@ -1,10 +1,7 @@
 Installation
 ############
 
-First, you need to get the source files. One way to get them is to download
-them from the github repository, using git::
-
-  git clone https://github.com/spiral-project/ihatemoney.git
+.. _installation-requirements:
 
 Requirements
 ============
@@ -13,31 +10,45 @@ Requirements
 
 * **Python**: either 2.7, 3.4, 3.5, 3.6 will work.
 * **A Backend**: to choose among MySQL, PostgreSQL, SQLite or Memory.
+* **Virtualenv** (recommended): `virtualenv` package under Debian/Ubuntu.
 
-We recommend to use `pip <https://pypi.python.org/pypi/pip/>`_ and
-`virtualenv <https://pypi.python.org/pypi/virtualenv>`_ but it will work
-without if you prefer.
+We recommend to use `virtualenv <https://pypi.python.org/pypi/virtualenv>`_ but
+it will work without if you prefer.
 
-If you have everything installed, you can just issue::
+If wondering about the backend, SQLite is the simplest and will work fine for
+most small to medium setups.
 
-    make serve
+Prepare virtualenv (recommended)
+================================
 
-Alternatively, you can also use the `requirements.txt` file to install the
-dependencies yourself (that's what the `make serve` does). That would be::
+Choose an installation path, here `/home/john/ihatemoney`.
 
-     pip install -r requirements.txt
+Create a virtualenv::
 
-And then run the application::
+    virtualenv  -p /usr/bin/python3 /home/john/ihatemoney
 
-    cd ihatemoney
-    python run.py
+Activate the virtualenv::
 
-In any case, you can point your browser at `http://localhost:5000 <http://localhost:5000>`_.
-It's as simple as that!
+    source /home/john/ihatemoney/bin/activate
 
-In case you want to update to newer versions, you can just run the "update" command::
+.. note:: You will have to re-issue that ``source`` command if you open a new
+          terminal.
 
-  make update
+Install
+=======
+
+Install the latest release with pip::
+
+  pip install ihatemoney
+
+Test it
+=======
+
+Once installed, you can start a test server::
+
+  ihatemoney runserver
+
+And point your browser at `http://localhost:5000 <http://localhost:5000>`_.
 
 Deploy it
 =========
@@ -59,12 +70,19 @@ With Apache and mod_wsgi
 With Nginx, Gunicorn and Supervisord
 ------------------------------------
 
-1. Add the lines in conf/supervisord.conf to your supervisord.conf file.
-2. Copy and paste the content of conf/nginx.conf in your nginx conf file.
-3. reload both nginx and supervisord. It should be working ;)
+.. note:: For the 3 configuration files mentioned below, you will need to fix
+          the paths to reflect yours.
+
+1. Copy *conf/gunicorn.conf.py* to */etc/ihatemoney/gunicorn.conf.py*
+2. Copy *conf/supervisord.conf* to */etc/supervisor/conf.d/ihatemoney.conf*
+3. Copy *conf/nginx.conf* with your nginx vhosts [#nginx-vhosts]_
+4. Reload both nginx and supervisord. It should be working ;)
 
 Don't forget to set the right permission for your files !
 
+.. [#nginx-vhosts] typically, */etc/nginx/conf.d/* or
+   */etc/nginx/sites-available*, depending on your distribution.
+
 Configuration
 =============
 
@@ -72,6 +90,8 @@ ihatemoney relies on a configuration file. If you run the application for the
 first time, you will need to take a few moments to configure the application
 properly.
 
+.. warning:: You **must** customize the ``SECRET_KEY`` on a production installation.
+
 +----------------------------+---------------------------+----------------------------------------------------------------------------------------+
 | Setting name               |  Default                  | What does it do?                                                                       |
 +============================+===========================+========================================================================================+
@@ -90,6 +110,9 @@ properly.
 | ADMIN_PASSWORD             |                           | To generate the proper password HASH, use ``ihatemoney generate_password_hash``        |
 |                            |                           | and copy its output into the value of *ADMIN_PASSWORD*.                                |
 +----------------------------+---------------------------+----------------------------------------------------------------------------------------+
+| APPLICATION_ROOT           |  ``""``                   | If empty, ihatemoney will be served at domain root (e.g: *http://domain.tld*), if set  |
+|                            |                           | to ``"foo"``, it will be served from a "folder" (e.g: *http://domain.tld/foo*)         |
++----------------------------+---------------------------+----------------------------------------------------------------------------------------+
 
 In a production environment
 ---------------------------
@@ -105,9 +128,3 @@ the IHATEMONEY_SETTINGS_FILE_PATH environment variable.
 e.g.::
 
     $ export IHATEMONEY_SETTINGS_FILE_PATH="/path/to/your/conf/file.cfg"
-
-Note that you can also pass additional flask parameters with this file.
-e.g. If you want to prefix your URLs to serve ihatemonney in the *folder*
-of a domain, use the following: ::
-
-    APPLICATION_ROOT='/budget'