diff --git a/conf/apache-vhost.conf b/conf/apache-vhost.conf index b26feaa5..1a84e7f7 100644 --- a/conf/apache-vhost.conf +++ b/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 @@ -12,5 +12,7 @@ Order deny,allow Allow from all -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/ diff --git a/conf/gunicorn.conf.py b/conf/gunicorn.conf.py index 8412a10c..017a6709 100644 --- a/conf/gunicorn.conf.py +++ b/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" diff --git a/conf/nginx.conf b/conf/nginx.conf index 9ae2ca0d..0fe26f02 100644 --- a/conf/nginx.conf +++ b/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; } diff --git a/conf/supervisord.conf b/conf/supervisord.conf index 1b5dbbf0..98bb4eb4 100644 --- a/conf/supervisord.conf +++ b/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 diff --git a/docs/contributing.rst b/docs/contributing.rst index b0a829f4..d2bdbcca 100644 --- a/docs/contributing.rst +++ b/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 `_, +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 `_. +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 `_. Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I will update the issue tracker with your feedback. diff --git a/docs/installation.rst b/docs/installation.rst index ade647f9..e0f70df3 100644 --- a/docs/installation.rst +++ b/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 `_ and -`virtualenv `_ but it will work -without if you prefer. +We recommend to use `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 `_. -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 `_. 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'