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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
Installation
############
We lack some knowledge about packaging to make Ihatemoney installable on mainstream
Linux distributions. If you want to give us a hand on the topic, please check-out
`the issue about debian packaging <https://github.com/spiral-project/ihatemoney/issues/227>`_.
If you are using Yunohost (a server operating system aiming to make self-hosting accessible to anyone),
you can use the `Ihatemoney package <https://github.com/YunoHost-Apps/ihatemoney_ynh>`_.
Otherwise, follow these instructions to install it manually:
.. _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>`_.
.. _virtualenv-preparation:
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*.
Production values are recommended values for use in production.
+-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+
| 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`_. |
| | | |
| | | **Production value:** Set it to some path on your disk. Typically |
| | | ``sqlite:///home/ihatemoney/ihatemoney.db``. Do *not* store it under ``/tmp`` as this |
| | | folder is cleared at each boot. |
+-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+
| SECRET_KEY | ``tralala`` | The secret key used to encrypt the cookies. |
| | | |
| | | **Production value:** `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. |
| | | |
| | | **Production value:** Any tuple you want. |
+-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+
| ACTIVATE_DEMO_PROJECT | ``True`` | If set to `True`, a demo project will be available on the frontpage. |
| | | |
| | | **Production value:** Usually, you will want to set it to ``False`` for a private |
| | | instance. |
+-------------------------------+---------------------------------+----------------------------------------------------------------------------------------+
| | | Hashed password to access protected endpoints. If left empty, all administrative |
| ADMIN_PASSWORD | ``""`` | tasks are disabled. |
| | | |
| | | **Production value:** 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"
|
