1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
Installation
############
.. _installation-requirements:
Requirements
============
«Ihatemoney» depends on:
* **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.
.. 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)
================================
Choose an installation path, here `/home/john/ihatemoney`.
Create a virtualenv::
virtualenv -p /usr/bin/python3 /home/john/ihatemoney
Activate the virtualenv::
source /home/john/ihatemoney/bin/activate
.. note:: You will have to re-issue that ``source`` command if you open a new
terminal.
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
=========
Now, if you want to deploy it on your own server, you have many options.
Three 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!*
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. 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
------------------------------------
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 ::
ihatemoney generate-config supervisord.conf > /etc/supervisor/conf.d/ihatemoney.conf
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.
With Docker
-----------
Build the image::
docker build -t ihatemoney --build-arg INSTALL_FROM_PYPI=True .
Start a daemonized Ihatemoney container::
docker run -d -p 8000:8000 ihatemoney
Ihatemoney is now available on http://localhost:8000.
All Ihatemoney settings can be passed with ``-e`` parameters
e.g. with a secure ``SECRET_KEY``, an external mail server and an external database::
docker run -d -p 8000:8000 \
-e SECRET_KEY="supersecure" \
-e SQLALCHEMY_DATABASE_URI="mysql+pymysql://user:pass@172.17.0.5/ihm" \
-e MAIL_SERVER=smtp.gmail.com \
-e MAIL_PORT=465 \
-e MAIL_USERNAME=your-email@gmail.com \
-e MAIL_PASSWORD=your-password \
-e MAIL_USE_SSL=True \
ihatemoney
A volume can also be specified to persist the default database file::
docker run -d -p 8000:8000 -v /host/path/to/database:/database ihatemoney
The following gunicorn parameters are also available::
GUNICORN_NUM_WORKERS (default: 3)
Configuration
=============
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.
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.::
$ export IHATEMONEY_SETTINGS_FILE_PATH="/path/to/your/conf/file.cfg"
|
