diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/installation.rst | 135 |
1 files changed, 82 insertions, 53 deletions
diff --git a/docs/installation.rst b/docs/installation.rst index 3f2c653..9fd96b7 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -18,6 +18,8 @@ it will work without if you prefer. If wondering about the backend, SQLite is the simplest and will work fine for most small to medium setups. +.. note:: If curious, source config templates can be found in the `project git repository <https://github.com/spiral-project/ihatemoney/tree/master/ihatemoney/conf-templates>`_. + Prepare virtualenv (recommended) ================================ @@ -57,28 +59,56 @@ Now, if you want to deploy it on your own server, you have many options. Two of them are documented at the moment. *Of course, if you want to contribute another configuration, feel free to open a -pull-request against this repository!*. +pull-request against this repository!* + + +Whatever your installation option is… +-------------------------------------- + +1. Initialize the ihatemoney directories:: + + mkdir /etc/ihatemoney /var/lib/ihatemoney + +2. Generate settings:: + + ihatemoney generate-config ihatemoney.cfg > /etc/ihatemoney/ihatemoney.cfg + chmod 740 /etc/ihatemoney/ihatemoney.cfg + +You probably want to adjust `/etc/ihatemoney/ihatemoney.cfg` contents, you may +do it later, see `Configuration`_. + With Apache and mod_wsgi ------------------------ -1. Install Apache and mod_wsgi - libapache2-mod-wsgi(-py3) for Debian based and mod_wsgi for RedHat based distributions - -2. Create an Apache virtual host based on the sample configuration file in `conf/apache-vhost.conf` -3. Adapt it to your paths and specify your virtualenv path if you use one +1. Fix permissions (considering `www-data` is the user running apache):: + + chgrp www-data /etc/ihatemoney/ihatemoney.cfg + chown www-data /var/lib/ihatemoney + +2. Install Apache and mod_wsgi - libapache2-mod-wsgi(-py3) for Debian based and mod_wsgi for RedHat based distributions - +3. Create an Apache virtual host, the command ``ihatemoney generate-config apache-vhost.conf`` will output a good starting point (read and adapt it) 4. Activate the virtual host if needed and restart Apache With Nginx, Gunicorn and Supervisord ------------------------------------ -.. note:: For the 3 configuration files mentioned below, you will need to fix - the paths to reflect yours. +1. Create a dedicated unix user (here called `ihatemoney`), required dirs, and fix permissions:: + + useradd ihatemoney + chown ihatemoney /var/lib/ihatemoney/ + chgrp ihatemoney /etc/ihatemoney/ihatemoney.cfg + +2. Create gunicorn config file :: + + ihatemoney generate-config gunicorn.conf.py > /etc/ihatemoney/gunicorn.conf.py + +3. Create supervisor config file :: -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 ;) + ihatemoney generate-config supervisord.conf > /etc/supervisor/conf.d/ihatemoney.conf -Don't forget to set the right permission for your files ! +4. Copy (and adapt) output of ``ihatemoney generate-config conf/nginx.conf`` with your nginx vhosts [#nginx-vhosts]_ +5. Reload both nginx and supervisord. It should be working ;) .. [#nginx-vhosts] typically, */etc/nginx/conf.d/* or */etc/nginx/sites-available*, depending on your distribution. @@ -90,48 +120,47 @@ 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? | -+===============================+=================================+==================================================================================+ -| SQLALCHEMY_DATABASE_URI | ``sqlite:///tmp/ihatemoney.db`` | Specifies the type of backend to use and its location. More information | -| | | on the format used can be found on `the SQLAlchemy documentation | -| | | <http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls>`_. | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| SECRET_KEY | ``tralala`` | The secret key used to encrypt the cookies. **This needs to be changed**. | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| MAIL_DEFAULT_SENDER | ``("Budget manager", | A python tuple describing the name and email adress to use when sending | -| | "budget@notmyidea.org")`` | emails. | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| ACTIVATE_DEMO_PROJECT | ``True`` | If set to `True`, a demo project will be available on the frontpage. | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| | | Hashed password to access protected endpoints. If left empty, all administrative | -| ADMIN_PASSWORD | ``""`` | tasks are disabled. | -| | | To generate the proper password HASH, use ``ihatemoney generate_password_hash`` | -| | | and copy the output into the value of *ADMIN_PASSWORD*. | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| ALLOW_PUBLIC_PROJECT_CREATION | ``True`` | If set to `True`, everyone can create a project without entering the admin password | -| | | If set to `False`, the password needs to be entered (and as such, defined in the | -| | | settings). | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| ACTIVATE_ADMIN_DASHBOARD | ``False`` | If set to `True`, the dashboard will become accessible entering the admin password | -| | | If set to `True`, a non empty ADMIN_PASSWORD needs to be set | -+-------------------------------+---------------------------+----------------------------------------------------------------------------------------+ -| 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 ---------------------------- - -Make a copy of ``ihatemoney/default_settings.py`` and name it ``ihatemoney.cfg``. -Then adjust the settings to your needs and move this file to -``/etc/ihatemoney/ihatemoney.cfg``. - -This is the default path of the settings but you can also place it -elsewhere and pass the configuration file path to the application using -the IHATEMONEY_SETTINGS_FILE_PATH environment variable. +Defaults given here, are those for development mode. To know defaults on your +deployed instance, simply look at your *ihatemoney.cfg*. + + ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| Setting name | Default | What does it do? | ++===============================+=================================+========================================================================================+ +| SQLALCHEMY_DATABASE_URI | ``sqlite:///tmp/ihatemoney.db`` | Specifies the type of backend to use and its location. More information on the | +| | | format used can be found on `the SQLAlchemy documentation`_. | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| SECRET_KEY | ``tralala`` | The secret key used to encrypt the cookies. `ihatemoney conf-example ihatemoney.cfg` | +| | | sets it to something random, which is good. | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| MAIL_DEFAULT_SENDER | ``("Budget manager", | A python tuple describing the name and email adress to use when sending | +| | "budget@notmyidea.org")`` | emails. | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| ACTIVATE_DEMO_PROJECT | ``True`` | If set to `True`, a demo project will be available on the frontpage. | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| | | Hashed password to access protected endpoints. If left empty, all administrative | +| ADMIN_PASSWORD | ``""`` | tasks are disabled. | +| | | To generate the proper password HASH, use ``ihatemoney generate_password_hash`` | +| | | and copy the output into the value of *ADMIN_PASSWORD*. | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| ALLOW_PUBLIC_PROJECT_CREATION | ``True`` | If set to `True`, everyone can create a project without entering the admin password | +| | | If set to `False`, the password needs to be entered (and as such, defined in the | +| | | settings). | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| ACTIVATE_ADMIN_DASHBOARD | ``False`` | If set to `True`, the dashboard will become accessible entering the admin password | +| | | If set to `True`, a non empty ADMIN_PASSWORD needs to be set | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ +| 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*) | ++-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+ + +.. _the SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls + +Using an alternate settings path +-------------------------------- + +You can put your settings file where you want, and pass its path to the +application using the ``IHATEMONEY_SETTINGS_FILE_PATH`` environment variable. e.g.:: |