diff --git a/docs/api.rst b/docs/api.rst index 10a626ee..a0394715 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -4,8 +4,7 @@ The REST API All of what's possible to do with the website is also possible via a web API. This document explains how the API is organized and how you can query it. -By default, the API talks JSON. There is no other way to speak with it -currently. +The only supported data format is JSON. Overall organisation ==================== @@ -13,7 +12,7 @@ Overall organisation You can access three different things: projects, members and bills. You can also get the balance for a project. -For the examples, I'm using curl, feel free to use whatever you want to do the +The examples here are using curl, feel free to use whatever you want to do the same thing, curl is not a requirement. Authentication @@ -33,17 +32,17 @@ Projects You can't list projects, for security reasons. But you can create, update and delete one directly from the API. -The URLs are `/api/projects` and `/api/projects/`. +The URLs are ``/api/projects`` and ``/api/projects/``. Creating a project ~~~~~~~~~~~~~~~~~~ A project needs the following arguments: -* `name`: The project name (string) -* `id`: the project identifier (string without special chars or spaces) -* `password`: the project password / secret code (string) -* `contact_email`: the contact email +* ``name``: The project name (string) +* ``id``: the project identifier (string without special chars or spaces) +* ``password``: the project password / secret code (string) +* ``contact_email``: the contact email :: @@ -85,7 +84,7 @@ Getting information about the project:: Updating a project ~~~~~~~~~~~~~~~~~~ -Updating a project is done with the `PUT` verb:: +Updating a project is done with the ``PUT`` verb:: $ curl --basic -u yay:yay -X PUT\ https://ihatemoney.org/api/projects/yay -d\ @@ -101,7 +100,7 @@ Just send a DELETE request ont the project URI :: Members ------- -You can get all the members with a `GET` on `/api/projects//members`:: +You can get all the members with a ``GET`` on ``/api/projects//members``:: $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/members\ [{"weight": 1, "activated": true, "id": 31, "name": "Arnaud"}, @@ -109,20 +108,21 @@ You can get all the members with a `GET` on `/api/projects//members`:: {"weight": 1, "activated": true, "id": 33, "name": "Olivier"}, {"weight": 1, "activated": true, "id": 34, "name": "Fred"}] -Add a member with a `POST` request on `/api/projects//members`:: +Add a member with a ``POST`` request on ``/api/projects//members``:: $ curl --basic -u demo:demo -X POST\ https://ihatemoney.org/api/projects/demo/members -d 'name=tatayoyo' 35 -You can also `PUT` a new version of a member (changing its name):: +You can also ``PUT`` a new version of a member (changing its name):: $ curl --basic -u demo:demo -X PUT\ https://ihatemoney.org/api/projects/demo/members/36\ -d 'name=yeaaaaah' {"activated": true, "id": 36, "name": "yeaaaaah", "weight": 1} -Delete a member with a `DELETE` request on `/api/projects//members/`:: +Delete a member with a ``DELETE`` request on +``/api/projects//members/``:: $ curl --basic -u demo:demo -X DELETE\ https://ihatemoney.org/api/projects/demo/members/35 @@ -131,18 +131,21 @@ Delete a member with a `DELETE` request on `/api/projects//members//bills` :: +You can get the list of bills by doing a ``GET`` on +``/api/projects//bills`` :: $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/bills -Add a bill with a `POST` query on `/api/projects//bills`. you need the +Add a bill with a ``POST`` query on ``/api/projects//bills``. you need the following params: -* `date`: the date of the bill; defaults to current date if not provided. (yyyy-mm-dd) -* `what`: what have been payed -* `payer`: by who ? (id) -* `payed_for`: for who ? (id, to set multiple id use a list, e.g. `["id1", "id2"]`) -* `amount`: amount payed +* ``date``: the date of the bill; defaults to current date if not + provided. (format is ``yyyy-mm-dd``) +* ``what``: what have been payed +* ``payer``: by who ? (id) +* ``payed_for``: for who ? (id, to set multiple id use a list, + e.g. ``["id1", "id2"]``) +* ``amount``: amount payed Returns the id of the created bill :: @@ -151,15 +154,16 @@ Returns the id of the created bill :: -d "date=2011-09-10&what=raclette&payer=31&payed_for=31&amount=200" 80 -You can also `PUT` a new version of the bill at -`/api/projects//bills/`:: +You can also ``PUT`` a new version of the bill at +``/api/projects//bills/``:: $ curl --basic -u demo:demo -X PUT\ https://ihatemoney.org/api/projects/demo/bills/80\ -d "date=2011-09-10&what=raclette&payer=31&payed_for=31&amount=250" 80 -And you can of course `DELETE` them at `/api/projects//bills/`:: +And you can of course ``DELETE`` them at +``/api/projects//bills/``:: $ curl --basic -u demo:demo -X DELETE\ https://ihatemoney.org/api/projects/demo/bills/80\ @@ -169,7 +173,8 @@ And you can of course `DELETE` them at `/api/projects//bills/`:: Statistics ---------- -You can get some project stats with a `GET` on `/api/projects//statistics`:: +You can get some project stats with a ``GET`` on +``/api/projects//statistics``:: $ curl --basic -u demo:demo https://ihatemoney.org/api/projects/demo/statistics [ diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 00000000..4e04e7a6 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,122 @@ +.. _configuration: + +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. + +The default values given here are those for the development mode. +To know defaults on your deployed instance, simply look at your +``ihatemoney.cfg`` file. + +"Production values" are the recommended values for use in production. + +`SQLALCHEMY_DATABASE_URI` +------------------------- + +Specifies the type of backend to use and its location. More information on the +format used can be found on `the SQLAlchemy documentation`_. + +- **Default value:** ``sqlite:///tmp/ihatemoney.db`` +- **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. + +If you're using PostgreSQL, Your client must use utf8. Unfortunately, +PostgreSQL default is to use ASCII. Either change your client settings, +or specify the encoding by appending ``?client_encoding=utf8`` to the +connection string. + +`SECRET_KEY` +------------ + +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` +--------------------- + +A python tuple describing the name and email address to use when sending +emails. + +- **Default value:** ``("Budget manager", "budget@notmyidea.org")`` +- **Production value:** Any tuple you want. + +`ACTIVATE_DEMO_PROJECT` +----------------------- + +If set to `True`, a demo project will be available on the frontpage. + +- **Default value:** ``True`` +- **Production value:** Usually, you will want to set it to ``False`` for a + private instance. + +`ADMIN_PASSWORD` +---------------- + +Hashed password to access protected endpoints. If left empty, all +administrative tasks are disabled. + +- **Default value:** ``""`` (empty string) +- **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` +------------------------------- + +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). + +- **Default value:** : ``True``. + + +`ACTIVATE_ADMIN_DASHBOARD` +-------------------------- + +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. + +- **Default value**: ``False`` + +`APPLICATION_ROOT` +------------------ + +If empty, ihatemoney will be served at domain root (e.g: *http://domain.tld*), +if set to ``"somestring"``, it will be served from a "folder" +(e.g: *http://domain.tld/somestring*). + +- **Default value:** ``""`` (empty string) + +.. _the SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls + +Configuring emails sending +-------------------------- + +By default, Ihatemoney sends emails using a local SMTP server, but it's +possible to configure it to act differently, thanks to the great +`Flask-Mail project `_ + +* **MAIL_SERVER** : default **'localhost'** +* **MAIL_PORT** : default **25** +* **MAIL_USE_TLS** : default **False** +* **MAIL_USE_SSL** : default **False** +* **MAIL_DEBUG** : default **app.debug** +* **MAIL_USERNAME** : default **None** +* **MAIL_PASSWORD** : default **None** +* **DEFAULT_MAIL_SENDER** : default **None** + +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. + +For instance :: + + export IHATEMONEY_SETTINGS_FILE_PATH="/path/to/your/conf/file.cfg" diff --git a/docs/contributing.rst b/docs/contributing.rst index d46c9ecf..ef6e24c0 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -49,16 +49,18 @@ In case you want to update to newer versions (from git), you can just run the "u Create database migrations -------------------------- -In case you need to modify the database schema, first update the models in ihatemoney/models.py. -Then run the following command to create a new database revision file:: +In case you need to modify the database schema, first update the models in +``ihatemoney/models.py``. Then run the following command to create a new +database revision file:: make create-database-revision If your changes are simple enough, the generated script will be populated with -the necessary migrations steps. You can edit the generated script. eg: to add data migrations. +the necessary migrations steps. You can edit the generated script. eg: to add +data migrations. -For complex migrations, it is recommended to start from an empty revision file which can be created -with the following command:: +For complex migrations, it is recommended to start from an empty revision file +which can be created with the following command:: make create-empty-database-revision @@ -75,7 +77,7 @@ You can also set the `TESTING` flag to `True` so no mails are sent (and no exception is raised) while you're on development mode. Then before running the application, declare its path with :: - $ export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg" + export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg" How to contribute ================= @@ -89,8 +91,8 @@ a developer or an user. As a developer -------------- -If you want to contribute code, you can write it and then issue a pull request on -github. Please, think about updating and running the tests before asking for +If you want to contribute code, you can write it and then issue a pull request +on github. Please, think about updating and running the tests before asking for a pull request as it will help us to maintain the code clean and running. To do so:: @@ -109,14 +111,14 @@ As a translator Collect all new strings to translate:: - $ make update-translations + make update-translations - Add missing translations to *.po* files inside *translations/* dir using your - favorite text editor. +Add missing translations to *.po* files inside *translations/* dir using your +favorite text editor. - Compile them into *.mo* files:: +Compile them into *.mo* files:: - $ make build-translations + make build-translations Commit both *.mo* and *.po*. @@ -125,8 +127,8 @@ 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 `_. -Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I will -update the issue tracker with your feedback. +Or, if you prefer, you can send me an email to `alexis@notmyidea.org` and I +will update the issue tracker with your feedback. Thanks again! @@ -154,22 +156,18 @@ In order to prepare a new release, we are following the following steps: - Merge remaining pull requests; - Update :file:`CHANGELOG.rst` with the last changes; - Update :file:`CONTRIBUTORS`; -- Update known good versions of dependencies in ``requirements.txt`` with this command (from inside the venv): +- Update known good versions of dependencies in ``requirements.txt`` with this + command (from inside the venv):: -.. code-block:: bash + make build-requirements - $ make build-requirements -- If needed, recompress assets. It requires zopflipng: +- If needed, recompress assets. It requires zopflipng:: -.. code-block:: bash + make compress-assets - $ make compress-assets +Once this is done, use the "release" instruction:: -Once this is done, use the "release" instruction: - -.. code-block:: bash - - $ make release + make release And the new version should be published on PyPI. diff --git a/docs/index.rst b/docs/index.rst index 40b917ee..915f3243 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,6 +5,9 @@ I hate money It keeps track of who bought what, when, and for whom; and helps to settle the bills. +I hate money is written in python, using the `flask `_ +framework. It's developped with ease of use in mind, and is trying to +keep things simple. Hope you (will) like it! Table of content ================ @@ -13,6 +16,7 @@ Table of content :maxdepth: 1 installation + configuration upgrade api contributing diff --git a/docs/installation.rst b/docs/installation.rst index d86dfcdd..ab8fc577 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,8 +2,8 @@ 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 `_. +Linux distributions. If you want to give us a hand on the topic, please +check-out `the issue about debian packaging `_. If you are using Yunohost (a server operating system aiming to make self-hosting accessible to anyone), you can use the `Ihatemoney package `_. @@ -98,8 +98,8 @@ 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!* +*Of course, if you want to contribute another configuration, feel free +to open a pull-request against this repository!* Whatever your installation option is… @@ -114,8 +114,8 @@ Whatever your installation option is… 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`_. +You probably want to adjust ``/etc/ihatemoney/ihatemoney.cfg`` contents, +you may do it later, see :ref:`configuration`. With Apache and mod_wsgi @@ -126,8 +126,11 @@ With Apache and mod_wsgi 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) +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/systemd @@ -180,13 +183,15 @@ Install Gunicorn:: systemctl enable ihatemoney.service systemctl start ihatemoney.service -4. Copy (and adapt) output of ``ihatemoney generate-config nginx.conf`` with your nginx vhosts [#nginx-vhosts]_ +4. Copy (and adapt) output of ``ihatemoney generate-config nginx.conf`` + with your nginx vhosts [#nginx-vhosts]_ 5. Reload nginx (and supervisord if you use it). It should be working ;) .. [#nginx-vhosts] typically, */etc/nginx/conf.d/* or */etc/nginx/sites-available*, depending on your distribution. -.. [#systemd-services] ``/etc/systemd/system/ihatemoney.service`` path may change depending on your distribution. +.. [#systemd-services] ``/etc/systemd/system/ihatemoney.service`` + path may change depending on your distribution. With Docker ----------- @@ -202,7 +207,8 @@ Start a daemonized Ihatemoney container:: 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:: +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" \ @@ -218,127 +224,8 @@ 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 -Additional gunicorn parameters can be passed using the docker ``CMD`` parameter. +Additional gunicorn parameters can be passed using the docker ``CMD`` +parameter. For example, use the following command to add more gunicorn workers:: docker run -d -p 8000:8000 ihatemoney -w 3 - -.. _configuration: - -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. - -`SQLALCHEMY_DATABASE_URI` -------------------------- - -Specifies the type of backend to use and its location. More information on the -format used can be found on `the SQLAlchemy documentation`_. - -- **default value:** ``sqlite:///tmp/ihatemoney.db`` -- **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. - -If you're using PostgreSQL, Your client must use utf8. Unfortunately, PostgreSQL default -is to use ASCII. Either change your client settings, or specify the encoding by appending -`?client_encoding=utf8` to the connection string. - -`SECRET_KEY` ------------- - -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` ---------------------- - -A python tuple describing the name and email address to use when sending emails. - -- **Default value:** ``("Budget manager", "budget@notmyidea.org")`` -- **Production value:** Any tuple you want. - -`ACTIVATE_DEMO_PROJECT` ------------------------ - -If set to `True`, a demo project will be available on the frontpage. - -- **Default value:** ``True`` -- **Production value:** Usually, you will want to set it to ``False`` for a - private instance. - -`ADMIN_PASSWORD` ----------------- - -Hashed password to access protected endpoints. If left empty, all administrative -tasks are disabled. - -- **Default value:** ``""`` (empty string) -- **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` -------------------------------- - -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). - -- **Default value:** : ``True``. - - -`ACTIVATE_ADMIN_DASHBOARD` --------------------------- - -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. - -- **Default value**: ``False`` - -`APPLICATION_ROOT` ------------------- - -If empty, ihatemoney will be served at domain root (e.g: *http://domain.tld*), -if set to ``"somestring"``, it will be served from a "folder" -(e.g: *http://domain.tld/somestring*). - -- **Default value:** ``""`` (empty string) - -.. _the SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls - -Configuring emails sending --------------------------- - -By default, Ihatemoney sends emails using a local SMTP server, but it's -possible to configure it to act differently, thanks to the great -`Flask-Mail project `_ - -* **MAIL_SERVER** : default **'localhost'** -* **MAIL_PORT** : default **25** -* **MAIL_USE_TLS** : default **False** -* **MAIL_USE_SSL** : default **False** -* **MAIL_DEBUG** : default **app.debug** -* **MAIL_USERNAME** : default **None** -* **MAIL_PASSWORD** : default **None** -* **DEFAULT_MAIL_SENDER** : default **None** - -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" diff --git a/docs/upgrade.rst b/docs/upgrade.rst index e48edcb0..39519b5d 100644 --- a/docs/upgrade.rst +++ b/docs/upgrade.rst @@ -66,7 +66,8 @@ development only. pip install ihatemoney -3. Fix your configuration file (paths *have* changed), depending on the software you use in your setup: +3. Fix your configuration file (paths *have* changed), depending on + the software you use in your setup: - **gunicorn**: ``ihatemoney generate-config gunicorn.conf.py`` (nothing critical changed, keeping your old config might be fine)