diff --git a/src/doc/administration/maintenance.rst b/src/doc/administration/maintenance.rst new file mode 100644 index 0000000000000000000000000000000000000000..8a3397614b409a4ad498d0d8898c79cd0eb69bd6 --- /dev/null +++ b/src/doc/administration/maintenance.rst @@ -0,0 +1,59 @@ + +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() + diff --git a/src/doc/conf.py b/src/doc/conf.py index a5dffccedb99fe118e49a587f4fcee12759cec59..4d601b8416df695319786229514630a6df55e6c1 100644 --- a/src/doc/conf.py +++ b/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), } diff --git a/src/doc/index.rst b/src/doc/index.rst index ae9541b7eb05cd17cdb3b71111a74679cf765eba..e41d318a2dbf7323e5cb327be1c7a3fe0b5d61ad 100644 --- a/src/doc/index.rst +++ b/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/* diff --git a/src/doc/tutorials.md b/src/doc/tutorials.md deleted file mode 100644 index b6fab0381f602884f3ea2c7906ab7cb7cfd28cf9..0000000000000000000000000000000000000000 --- a/src/doc/tutorials.md +++ /dev/null @@ -1,2 +0,0 @@ -# Tutorials -to be created