diff options
Diffstat (limited to 'docs/installation.rst')
| -rw-r--r-- | docs/installation.rst | 73 |
1 files changed, 45 insertions, 28 deletions
diff --git a/docs/installation.rst b/docs/installation.rst index ade647f..e0f70df 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 `virtualenv <https://pypi.python.org/pypi/virtualenv>`_ but +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. + +Prepare virtualenv (recommended) +================================ + +Choose an installation path, here `/home/john/ihatemoney`. + +Create a virtualenv:: + + virtualenv -p /usr/bin/python3 /home/john/ihatemoney -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. +Activate the virtualenv:: -If you have everything installed, you can just issue:: + source /home/john/ihatemoney/bin/activate - make serve +.. note:: You will have to re-issue that ``source`` command if you open a new + terminal. -Alternatively, you can also use the `requirements.txt` file to install the -dependencies yourself (that's what the `make serve` does). That would be:: +Install +======= - pip install -r requirements.txt +Install the latest release with pip:: -And then run the application:: + pip install ihatemoney - cd ihatemoney - python run.py +Test it +======= -In any case, you can point your browser at `http://localhost:5000 <http://localhost:5000>`_. -It's as simple as that! +Once installed, you can start a test server:: -In case you want to update to newer versions, you can just run the "update" command:: + ihatemoney runserver - make update +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' |