Merge branch 'f-backup' into 'dev'

DOC: document backup and restore

See merge request caosdb/caosdb-server!68

src/doc/administration/maintenance.rst

+
+Maintenance of the CaosDB Server
+================================
+
+Creating a Backup
+-----------------
+
+In order to create a full backup of CaosDB, the state of the SQL-Backend (MySQL, MariaDB)
+has to be saved and the internal file system of CaosDB (symbolic links to 
+file systems that are mounted and uploaded files) has to be saved.
+
+You find the documentation on how to backup the SQL-Backend  :any:`caosdb-mysqlbackend:Maintenance` 
+
+In order to save the file backend we recommend to tar the file system. However, 
+you could use other backup methods that allow to restore the file system.
+The CaosDB internal file system is located at the path defined by the 
+``FILE_SYSTEM_ROOT`` configuration variable (see :any:`configuration`).
+
+The command could look like::
+
+    tar czvf /path/to/new/backup /path/to/caosdb/filesystem.tar.gz
+
+
+You can also save the content of CaosDB using XML. This is **not recommended** since it is less reliable than a real SQL backup. However there may be cases in which an XML backup is desirable, e.g., when transferring entities between two different CaosDB instances.
+Collect the entities that you want to export in a :any:`caosdb-pylib:caosdb.common.models.Container`, here 
+named ``cont``. Then you can export the XML with::
+
+     from caosadvancedtools.export_related import invert_ids
+     from lxml import etree
+     invert_ids(cont)
+     xml = etree.tounicode(cont.to_xml(
+         local_serialization=True), pretty_print=True)
+
+     with open("caosdb_data.xml"), "w") as fi:
+         fi.write(xml)
+
+
+Restoring a Backup
+------------------
+
+.. note :
+    CaosDB should be offline before restoring data.
+
+If you want to restore the internal file system, simply replace it. E.g. if your
+Backup is a tarball::
+
+    tar xvf /path/to/caosroot.tar.gz
+
+
+You find the documentation on how to restore the data in the SQL-Backend  :any:`caosdb-mysqlbackend:Maintenance` 
+
+
+If you want to restore the entities exported to XML, you can do::
+
+     cont = db.Container()                                                                                                                                
+     with open("caosdb_data.xml") as fi:                                                                                                                           
+         cont = cont.from_xml(fi.read())                                                                                                                  
+     cont.insert()
+                                            

src/doc/conf.py

@@ -197,6 +197,7 @@ epub_exclude_files = ['search.html']
 intersphinx_mapping = {
     "python": ("https://docs.python.org/", None),
     "caosdb-pylib": ("https://caosdb.gitlab.io/caosdb-pylib/", None),
+    "caosdb-mysqlbackend": ("https://caosdb.gitlab.io/caosdb-mysqlbackend/", None),
 }
 
 

src/doc/index.rst

@@ -10,7 +10,6 @@ Welcome to caosdb-server's documentation!
 
    Getting started <README_SETUP>
    Concepts <concepts>
-   tutorials
    Query Language <CaosDB-Query-Language>
    administration/*
    development/*

src/doc/tutorials.md

-# Tutorials
-to be created