Extended documentation for how to update specific tables (#177)

HISTORY.rst

@@ -34,6 +34,7 @@ End-User Summary
   **This is a breaking change, new data and CLI must be used!**
 - Added feature to select multiple rows in results to create same annotation (#259)
 - Added parameter to Docker entrypoint file to accept number of gunicorn workers
+- Extended documentation for how to update specific tables (#177)
 
 Full Change List
 ================
@@ -69,6 +70,7 @@ Full Change List
 - Extending  columns of ``Hgnc`` to upstream update.
 - Added feature to select multiple rows in results to create same annotation (#259)
 - Added parameter to Docker entrypoint file to accept number of gunicorn workers
+- Extended documentation for how to update specific tables (#177)
 
 -------
 v0.23.9

docs_manual/admin_install.rst

@@ -158,3 +158,115 @@ You will observe that the database came with some demo data sets of public IGSR
 .. figure:: figures/admin/admin_view_project.png
     :align: center
     :width: 80%
+
+---------------------
+Updating the Database
+---------------------
+
+First, the tables that are to be updated should be generated. For this,
+follow the instructions in the
+`VarFish DB Downloader repository <https://github.com/bihealth/varfish-db-downloader/#building-specific-tables>`_.
+
+At this point you should have a folder structure available that resembles::
+
+    varfish-db-downloader/
+        GRCh37/
+            <table_group>/
+                <version>/
+                    <table>.tsv
+                    <table>.release_info
+        GRCh37/
+            [...]
+        noref/
+            [...]
+        import_versions.tsv
+        [...]
+
+If the HPO and OMIM tables are supposed to be updated, it would look like this::
+
+    varfish-db-downloader/
+        noref/
+            hpo/
+                20220126/
+                    Hpo.release_info
+                    Hpo.tsv
+                    HpoName.release_info
+                    HpoName.tsv
+            mim2gene/
+                20220126/
+                    Mim2geneMedgen.release_info
+                    Mim2geneMedgen.tsv
+        import_versions.tsv
+        [...]
+
+Copy this structure on to the machine where the Docker compose is running.
+Take Docker compose down (this will shut down your VarFish instance!):
+
+.. code-block:: bash
+
+    $ cd varfish-docker-compose  # make sure to be in the docker compose folder
+    $ docker-compose down
+
+Modify the ``docker-compose.yml`` file by finding the following entry::
+
+      varfish-web:
+        image: ghcr.io/bihealth/varfish-server:0.23.9-0
+        env_file:
+          - .env
+        networks:
+          - varfish
+        restart: unless-stopped
+        volumes:
+          - "/root/varfish-server-background-db-20201006:/data:ro"
+        [...]
+
+And add another volume that maps your directory into the container::
+
+        volumes:
+          - "/root/varfish-server-background-db-20201006:/data:ro"
+          - type: bind
+            source: varfish-db-downloader/
+            target: /data-db-downloader
+            read_only: true
+
+Start docker compose again:
+
+.. code-block:: bash
+
+    $ docker-compose up
+
+Once done, attach to your container:
+
+.. code-block:: bash
+
+    $ docker exec -it varfish-docker-compose_varfish-web_1 bash -i
+
+Switch to the application directory and start the import:
+
+.. code-block:: bash
+
+    varfish-web-container$ cd /usr/src/app
+    varfish-web-container$ python manage.py import_tables --tables-path /data-db-downloader
+
+The output of the command should look something like this::
+
+    Disabling autovacuum on all tables...
+    Hpo -- Importing Hpo 2022/01/26 (, source: /data-db-downloader/noref/hpo/20220126/Hpo.tsv) ...
+    Mim2geneMedgen -- Importing Mim2geneMedgen 2022/01/26 (, source: /data-db-downloader/noref/mim2gene/20220126/Mim2geneMedgen.tsv) ...
+    Hpo -- Removing old Hpo results.
+    Mim2geneMedgen -- Removing old Mim2geneMedgen results.
+    Mim2geneMedgen -- Importing new Mim2geneMedgen data
+    Hpo -- Importing new Hpo data
+    Mim2geneMedgen -- Finished importing Mim2geneMedgen 2022/01/26 (Mim2geneMedgen.tsv)
+    Hpo -- Finished importing Hpo 2022/01/26 (Hpo.tsv)
+    HpoName -- Importing HpoName 2022/01/26 (, source: /data-db-downloader/noref/hpo/20220126/HpoName.tsv) ...
+    HpoName -- Removing old HpoName results.
+    HpoName -- Importing new HpoName data
+    HpoName -- Finished importing HpoName 2022/01/26 (HpoName.tsv)
+    Enabling autovacuum on all tables...
+
+To verify the import, switch to the VarFish web interface, find the users menu
+on the top right corner and select the ``Import Release Info`` entry. The
+updated tables should have the latest version.
+
+.. figure:: figures/misc_ui/import_release_info.png