Commit d4fade38 authored by Reto Gantenbein's avatar Reto Gantenbein

Add upgrade guide

parent 5e8c6394
.. _roundcube__ref_changelog:
......@@ -10,6 +12,9 @@ and `human-readable changelog <>`__.
The current role maintainer_ is ganto_.
Refer to the :ref:`roundcube__ref_upgrade_notes` when you intend to upgrade to a
new release of this role.
`debops-contrib.roundcube master`_ - unreleased
.. _roundcube__ref_upgrade_notes:
Upgrade notes
The upgrade notes only describe necessary changes that you might need to make
to your setup in order to use a new role release. Refer to the
:ref:`roundcube__ref_changelog` for more details about what has changed.
From v0.1.3 to v.0.2.0
Due to changes in the role dependencies and some adjustments in the role's
default values, your setup is likely to break if you simply execute the
updated role. To avoid this, take care of the following issues:
- If you are using a custom playbook, make sure to review the changes in
- The following variables were replaced and therefore are not defined
anymore in the default variables:
- ``roundcube__nginx_server``
- ``roundcube__nginx_upstream_php5``
- ``roundcube__php5_packages``
- ``roundcube__php5_pool``
- ``roundcube__extra_packages``
In case your playbook is referencing one of them, make sure they are
properly defined in your inventory or update your playbook. If you are using
the example playbook but customized one of those variables in your Ansible
inventory update the definition accordingly.
- The default installation path defined in :envvar:`roundcube__www` changed.
If you didn't customize its value the Roundcube installation will be under
a new file system path after the installation.
**Upgrade procedure**
The following procedure is valid if you are using the role dependencies as
defined in the example playbook.
1. Make sure you have the latest version of the DebOps roles.
.. code:: shell
$ debops-update
2. Make sure you have the lastest version of the debops-contrib.roundcube_
role. In your DebOps project directory run:
.. code:: shell
$ ansible-galaxy install --force --no-deps --roles-path=ansible/roles debops-contrib.roundcube
2. Review the :ref:`roundcube__ref_changelog` and make sure your Ansible
inventory is adjusted to the variable changes (if necessary).
3. Remove the nginx virtual host and PHP definitions created by the
debops.nginx_ role from the Roundcube server:
.. code:: shell
# rm /etc/nginx/{sites-available,sites-enabled}/
# rm /etc/nginx/conf.d/upstream_php5_roundcube.conf
4. Run the role (e.g. via example playbook):
.. code:: shell
$ debops ansible/roles/debops-contrib.roundcube/docs/playbooks/roundcube.yml
5. In case you are using the default configuration copy the Roundcube
SQLite database containing the user settings to the new installation path.
.. code:: shell
$ cp /srv/www/roundcube/sites/ \
6. If you manually installed some additional plugins you might need to re-
install or update them for the new Roundcube version.
.. _roundcube__ref_getting_started:
Getting started
.. contents::
.. _roundcube__ref_default_setup:
Default setup
......@@ -13,6 +17,8 @@ release which is then accessible via ``https://roundcube.<your-domain>``.
.. _nginx:
.. _roundcube__ref_example_inventory:
Example inventory
......@@ -22,6 +28,8 @@ You can install Roundcube on a host by adding it to the
.. _roundcube__ref_example_playbook:
Example playbook
.. _debops.roundcube:
.. _debops-contrib.roundcube:
Ansible role: debops-contrib.roundcube
......@@ -13,6 +13,7 @@ Ansible role: debops-contrib.roundcube
Local Variables:
.. include:: ../UPGRADE.rst
Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment