update docs (#2018, #2046, #2047)

CHANGELOG.rst

@@ -14,6 +14,7 @@ Added
 - **General**
     - Python v3.11 support (#1922, #1978)
     - ``SESSION_COOKIE_AGE`` and ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` Django settings (#2015)
+    - Administrator upgrade guide in documentation (#2047)
 - **Irodsbackend**
     - Token auth support in ``BasicAuthView`` (#1999)
     - Django checks for enabled authentication methods (#1999)

docs_manual/source/_include/irods_env_update.rst

@@ -0,0 +1,9 @@
+.. note::
+
+    SODAR v1.0+ uses iRODS v4.3, which requires an updated client software and
+    environment. If you experience connection issues, ensure you are running on
+    the latest version iCommands or any other iRODS client(s) you use. You also
+    need to download a new ``irods_environment.json`` file in the
+    :ref:`ui_irods_info` application. Alternatively, edit your existing JSON
+    file and change the value of ``irods_authentication_scheme`` from ``PAM`` to
+    ``pam_password``.

docs_manual/source/admin_upgrade.rst

@@ -0,0 +1,118 @@
+.. _admin_upgrade:
+
+Upgrade Guide
+^^^^^^^^^^^^^
+
+This document contains administrator instructions for upgrading specific
+versions of SODAR. It assumes the use of the
+`SODAR Docker Compose <https://github.com/bihealth/sodar-docker-compose>`_
+environment.
+
+
+General Upgrades
+================
+
+For most SODAR versions, the following procedure for upgrading can be followed:
+
+1. Pull and check out the ``sodar-docker-compose`` release corresponding to the
+   current SODAR server version.
+2. Review and update your environment variables to match and/or support those
+   recommended in the `env.example <https://github.com/bihealth/sodar-docker-compose/blob/main/env.example>`_
+   file found in the current ``sodar-docker-compose`` release. Especially make
+   sure ``SODAR_SERVER_VERSION`` is set to the latest version found in the
+   `sodar-server packages <https://github.com/bihealth/sodar-server/pkgs/container/sodar-server>`_
+   and that other image versions are as recommended in the example.
+3. Pull and build the images.
+4. Restart the Docker Compose network.
+
+For SODAR releases where breaking changes require additional actions, release
+specific procedures are listed below.
+
+All instructions assume you are running the previous major release of SODAR
+before performing the upgrade.
+
+
+.. _admin_upgrade_v1.0:
+
+v1.0
+====
+
+SODAR v1.0 contains breaking changes regarding upgrades to iRODS 4.3 and
+PostgreSQL >12. When upgrading from a previous version, it is recommended to do
+a clean install.
+
+.. warning::
+
+    This upgrade may result in loss of data if performed incorrectly. Make sure
+    your databases and other relevant files are backed up and follow the
+    instructions carefully. If working in a production environment, it is
+    recommended to take a snapshot of your host VM before proceeding.
+
+1. If it is running, bring down the Docker Compose network *except* for the
+   postgres container.
+
+- If not running, bring up the postgres container by itself.
+
+2. Export and backup your ``sodar`` and ``ICAT`` databases.
+
+- SSH into the postgres container as the ``postgres`` user.
+- Example: ``pg_dump -cv DATABASE-NAME > /tmp/DATABASE-NAME_yyyy-mm-dd.sql``
+- Make sure you export both databases.
+- Make sure you store the backups outside your Docker containers.
+- **OPTIONAL:** If you have made changes to iRODS config not present in the
+  ``sodar-docker-compose`` repository, e.g. changing the iRODS rule files,
+  also back up your iRODS config files at this point.
+- **OPTIONAL:** If you run an evaluation environment with the iRODS vault
+  stored in a local volume and accessed directly via ICAT, also consider
+  backing up your vault directory.
+
+3. Pull the latest release of ``sodar-docker-compose``.
+
+4. Delete the iRODS configuration directory and PostgreSQL database volume.
+
+- **WARNING:** This will result in loss of data, so make sure you have
+  successfully backed up everything before proceeding!
+- Example: ``sudo rm -rf config/irods/etc/ volumes/postgres``
+
+5. Update your ``.env`` file (or environment variables in your deployment
+   scripts) to be compatible with the ``env.example`` file.
+
+6. Run ``./init.sh`` (or the corresponding command in your deployment scripts)
+   to recreate directories.
+
+7. Bring up the Docker Compose network.
+
+- If something fails in your SODAR or iRODS install, repeat steps 4-7.
+
+8. Once SODAR and iRODS are successfully set up, bring down the Docker Compose
+   network *except* for the postgres container.
+
+9. Replace the ``sodar`` and ``ICAT`` databases in postgres with your database
+   exports.
+
+- Example: ``psql DATABASE-NAME < /tmp/DATABASE-NAME_yyyy-mm-dd.sql``
+
+10. Restart the full Docker Compose network.
+
+- ``sodar-web`` will migrate your SODAR database on restart.
+- ``irods`` will use the previously backed up database on restart.
+
+
+.. _admin_upgrade_v0.15:
+
+v0.15
+=====
+
+To enable support for custom ISA-Tab templates, make sure to add
+``isatemplates_backend`` to ``SODAR_ENABLED_BACKEND_PLUGINS`` in your
+environment variables.
+
+
+.. _admin_upgrade_v0.14:
+
+v0.14
+=====
+
+Upon deploying this release on an existing instance, admins must run the
+``syncmodifyapi`` management command. This will update project user access in
+iRODS according to the role inheritance update introduced in SODAR Core v0.13.

docs_manual/source/api_irodsinfo.rst

@@ -25,17 +25,3 @@ API Views
 .. currentmodule:: irodsinfo.views_api
 
 .. autoclass:: IrodsEnvRetrieveAPIView
-<<<<<<< HEAD
-
-
-Versioning
-==========
-
-For accept header versioning, the following header is expected in the current
-SODAR version:
-
-.. code-block:: console
-
-    Accept: application/vnd.bihealth.sodar+json; version=0.15.1
-=======
->>>>>>> update rest api versioning (#1936)

docs_manual/source/api_landingzones.rst

@@ -35,17 +35,3 @@ API Views
 .. autoclass:: ZoneSubmitDeleteAPIView
 
 .. autoclass:: ZoneSubmitMoveAPIView
-<<<<<<< HEAD
-
-
-Versioning
-==========
-
-For accept header versioning, the following header is expected in the current
-SODAR version:
-
-.. code-block:: console
-
-    Accept: application/vnd.bihealth.sodar+json; version=0.15.1
-=======
->>>>>>> update rest api versioning (#1936)

docs_manual/source/api_samplesheets.rst

@@ -71,17 +71,3 @@ iRODS Data Requests
 .. autoclass:: IrodsDataRequestAcceptAPIView
 
 .. autoclass:: IrodsDataRequestRejectAPIView
-<<<<<<< HEAD
-
-
-Versioning
-==========
-
-For accept header versioning, the following header is expected in the current
-SODAR version:
-
-.. code-block:: console
-
-    Accept: application/vnd.bihealth.sodar+json; version=0.15.1
-=======
->>>>>>> update rest api versioning (#1936)

docs_manual/source/data_transfer_irods.rst

@@ -67,6 +67,8 @@ and can access data on the storage in your terminal.
 
 .. include:: _include/oidc_irods_token.rst
 
+.. include:: _include/irods_env_update.rst
+
 See `iRODS documentation <https://docs.irods.org/master/icommands/user/>`_
 for iCommands reference.
 

docs_manual/source/index.rst

@@ -136,6 +136,7 @@ Table of Contents
     admin_commands
     admin_settings
     admin_custom
+    admin_upgrade
 
 .. toctree::
     :maxdepth: 1
@@ -156,4 +157,4 @@ Table of Contents
     :name: sodar_history
 
     Release Notes <sodar_release_notes>
-    Full Changelog <sodar_changelog>
+    Changelog <sodar_changelog>

docs_manual/source/sodar_release_notes.rst

@@ -30,30 +30,26 @@ Release for SODAR Core v1.0 upgrade, iRODS v4.3 upgrade and feature updates.
 - Upgrade to Postgres v16
 - Upgrade to python-irodsclient v2.2.0
 - Upgrade to SODAR Core v1.0.3
-- SODAR Core v1.0 updates: OIDC auth support, new REST API versioning,
-  owner/delegate remote sync controls, etc
+- `SODAR Core v1.0 updates <https://sodar-core.readthedocs.io/en/latest/major_changes.html#v1-0-3-2024-12-12>`_:
+  OIDC auth support, new REST API versioning, owner/delegate remote sync
+  controls, etc
 - Upgrade to Django v4.2
 - Remove Python v3.8 support
 - Remove Postgres <12 support
 - Remove iRODS <4.3 support
 
-Migration Guide
----------------
-
-Python Version Support
-    Python v3.11 is now the recommended Python version. Support for v3.8 has
-    been dropped. It is recommended to upgrade your deployment for Python v3.11.
-PostgreSQL Version Support
-    This release drops support for Postgres versions below v12. The recommended
-    version is v16. Note that if you run both the SODAR Server and the iRODS
-    iCAT server on the same PostgreSQL database server, you may need to upgrade
-    your iRODS server. The CUBI iRODS v4.2 Docker image does not support
-    Postgres >11. See the latest dev version of sodar-docker-compose for more
-    information.
-iRODS Version Support
+:ref:`Administrator upgrade guide for v1.0 <admin_upgrade_v1.0>`
+
+User Upgrade Guide
+------------------
+
+iRODS v4.3 Required
     The minimum supported version of iRODS from this version onwards is v4.3.3.
-    Please upgrade the iRODS servers used in your SODAR installation. If using
-    sodar-docker-compose, see upgrading instructions in the repository.
+    Please ensure your iCommands package is upgraded to the latest version.
+    Your ``irods_environment.json`` file also needs to be updated. It is
+    recommended to download a new environment file in the :ref:`ui_irods_info`
+    application. Alternatively, edit the JSON file and change the value of
+    ``irods_authentication_scheme`` from ``PAM`` to ``pam_password``.
 REST API Versioning Changes
     REST API versioning has changed in SODAR Core v1.0 and SODAR Server v1.0.
     Accept header versioning is now specific to each Django app providing their
@@ -62,12 +58,6 @@ REST API Versioning Changes
     version numbers. If your clients or scripts make use of the versioning, you
     will need to consult the REST API documentation and update them accordingly.
 
-.. warning::
-
-    It is strongly recommended to backup your SODAR and iRODS databases before
-    upgrading to this version due to the changed database requirements. Also it
-    is strongly recommended to go through all documentation before upgrading.
-
 REST API Updates
 ----------------
 
@@ -114,13 +104,7 @@ Feature release.
 - Upgrade critical dependencies
 - Minor updates and bug fixes
 
-Migration Guide
----------------
-
-Isatemplates Backend
-    To enable support for custom ISA-Tab templates, make sure to add
-    ``isatemplates_backend`` to ``ENABLED_BACKEND_PLUGINS`` in your site's
-    Django settings.
+:ref:`Administrator upgrade guide for v0.15 <admin_upgrade_v0.15>`
 
 
 v0.14.2 (2024-03-15)
@@ -143,8 +127,8 @@ Release for minor updates, maintenance and bug fixes.
 - Minor updates and bug fixes
 - Upgrade to SODAR Core v0.13.4
 
-Migration Guide
----------------
+User Upgrade Guide
+------------------
 
 CRAM File Support
     This release adds support for CRAM files. They are linked in studies and IGV
@@ -169,8 +153,8 @@ Release for minor updates, maintenance and bug fixes.
 - Minor updates and bug fixes
 - Upgrade to SODAR Core v0.13.3
 
-Migration Guide
----------------
+User Upgrade Guide
+------------------
 
 Default IGV Genome
     The default IGV genome for cancer and germline projects has been changed
@@ -212,12 +196,7 @@ Major feature update.
 - Upgrade to SODAR Core v0.13.2
 - SODAR Core v0.13 updates: full role inheritance, finder role, etc.
 
-Migration Guide
----------------
-
-Upon deploying this release on an existing instance, admins must run the
-``syncmodifyapi`` management command. This will update project user access in
-iRODS according to the role inheritance update introduced in SODAR Core v0.13.
+:ref:`Administrator upgrade guide for v0.14 <admin_upgrade_v0.14>`
 
 
 v0.13.4 (2023-05-15)

docs_manual/source/ui_irods_info.rst

@@ -28,3 +28,5 @@ access any project data in iRODS you will need to be explicitly granted project
 access in SODAR.
 
 .. include:: _include/oidc_irods_token.rst
+
+.. include:: _include/irods_env_update.rst