diff options
| -rw-r--r-- | CHANGELOG.rst | 1 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/installation.rst | 2 | ||||
| -rw-r--r-- | docs/upgrade.rst | 78 |
4 files changed, 82 insertions, 0 deletions
diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2f3a037..32e4adf 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -32,6 +32,7 @@ Added - ACTIVATE_ADMIN_DASHBOARD setting (#262) - Link to the dashboard in the navigation bar (#262) - Dockerfile +- Documentation explaining the upgrade process Removed ======= diff --git a/docs/index.rst b/docs/index.rst index 8d96058..40b917e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Table of content :maxdepth: 1 installation + upgrade api contributing diff --git a/docs/installation.rst b/docs/installation.rst index 9a0a7a9..9a5bd5a 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -29,6 +29,8 @@ 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) ================================ diff --git a/docs/upgrade.rst b/docs/upgrade.rst new file mode 100644 index 0000000..9e48a98 --- /dev/null +++ b/docs/upgrade.rst @@ -0,0 +1,78 @@ +Upgrading +######### + +We keep `a ChangeLog +<https://github.com/spiral-project/ihatemoney/blob/master/CHANGELOG.rst>`_. Read +it before upgrading. + +Ihatemoney follows `semantic versioning <http://semver.org/>`_. So minor/patch +upgrades can be done blindly. + +General procedure +================= + +*(sufficient for minor/patch upgrades)* + +1. From the virtualenv (if any):: + + pip install -U ihatemoney + +2. Restart *supervisor*, or *Apache*, depending on your setup. + +You may also want to set new configuration variables (if any). They are +mentioned in the `ChangeLog +<https://github.com/spiral-project/ihatemoney/blob/master/CHANGELOG.rst>`_, but +this is **not required for minor/patch upgrades**, a safe default will be used +automatically. + +Version-specific instructions +============================= + +*(must read for major upgrades)* + +When upgrading from a major version to another, you **must** follow special +instructions: + +1.x → 2.x +--------- + +Switch from git installation to pip installation +++++++++++++++++++++++++++++++++++++++++++++++++ + +The recomended installation method is now using *pip*. Git is now intended for +development only. + +.. warning:: Be extra careful to not remove your sqlite database nor your + settings file, if they are stored inside the cloned folder. + +1. Delete the cloned folder + + +.. note:: If you are using a virtualenv, then the following commands should be run inside it (see + :ref:`virtualenv-preparation`). + + +2. Install ihatemoney with pip:: + + pip install ihatemoney + +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) + + - **supervisor** : ``ihatemoney generate-config supervisord.conf`` (mind the + ``command=`` line) + + - **apache**: ``ihatemoney generate-config apache-vhost.conf`` (mind the + ``WSGIDaemonProcess``, ``WSGIScriptAlias`` and ``Alias`` lines) +4. Restart *Apache* or *Supervisor*, depending on your setup. + +Upgrade ADMIN_PASSWORD to its hashed form +++++++++++++++++++++++++++++++++++++++++++ + +.. note:: Not required if you are not using the ADMIN_PASSWORD feature. + +``ihatemoney generate_password_hash`` will do the hashing job for you, just put + its result in the ``ADMIN_PASSWORD`` var from your `ihatemoney.cfg` and + restart *apache* or the *supervisor* job. |