diff --git a/docs/backend/upgrading/preparations.md b/docs/backend/upgrading/preparations.md index 85f8ecd45..602c4adc4 100644 --- a/docs/backend/upgrading/preparations.md +++ b/docs/backend/upgrading/preparations.md @@ -4,7 +4,7 @@ myst: "description": "Plone upgrade preparations" "property=og:description": "Plone upgrade preparations" "property=og:title": "Plone upgrade preparations" - "keywords": "Plone, upgrade, preparations" + "keywords": "Plone, upgrade, preparations, ZODB, collective.recipe.backup, buildout, backup, restore" --- @@ -12,7 +12,7 @@ myst: # Preparations -This chapter lists things to do before you migrate Plone. +This chapter describes things to do before you migrate Plone. (upgrade-gather-informationlabel)= @@ -56,18 +56,83 @@ If Plone is being upgraded at the same time as a Zope version, Plone will usuall Always back up your Plone site before upgrading. ``` -```{seealso} -See Plone 5.2 documentation, [Backing up your Plone deployment](https://5.docs.plone.org/manage/deploying/backup.html). -``` +This back up guide assumes the following. -```{todo} -Migrate the Plone 5.2 docs for Backing up your Plone deployment into Plone 6 docs. -``` +- You back up your Plone site. +- You back up your buildout and its caches. +- You back up your persistent data storage using a strategy that maintains data integrity without taking down your Plone site, that is performed periodically with adequate frequency, and that stores sufficient versions of your data. +- You've tested the restore process. + + +### Where's my data? + +Your Plone instance installation contains a directory {file}`./var`. +This directory is located in the same directory as the file {file}`buildout.cfg`. +It holds the frequently changing data files for the instance. +{file}`./var` contains the instance's log, process ID, and socket files. + +The following directories contain your instance's content. + + +#### {file}`./var/filestorage` + +The Zope Object Database ({term}`ZODB`) file storage is maintained in the directory {file}`./var/filestorage`. +The default file name is {file}`Data.fs`, although you could have multiple files or renamed it. +It's typically a large file which contains everything except {term}`blob`s. + +The other files in this directory with the file extensions of `.index`, `.lock`, `.old`, or `.tmp` are ephemeral, and will be recreated by Zope if they're absent. + + +#### {file}`./var/blobstorage` + +The directory {file}`./var/blobstorage` contains a deeply nested directory hierarchy that contains the blobs of your database. +These files may include PDFs, images, videos, office automation files, and other binary objects. + +`filestorage` and `blobstorage` are maintained synchronously. +`filestorage` has references to blobs in `blobstorage`. +If the two storages are not synchronized, you'll get errors whenever their data is accessed. + + +### `collective.recipe.backup` + +[`collective.recipe.backup`](https://pypi.org/project/collective.recipe.backup/) is a well-maintained buildout recipe that maintains data integrity for a live Plone database. + +See its `README.md`'s section [Introduction](https://github.com/collective/collective.recipe.backup?tab=readme-ov-file#introduction) for its buildout recipe configuration. + +The recipe supports several options, all of which are documented its `README.md`'s section [Supported options](https://github.com/collective/collective.recipe.backup/blob/master/README.rst#supported-options). + +Perhaps the most useful option is `location`, which sets the destination for backup files. +Its default value is `var/backups`, inside the buildout directory. +The backup destination, may be any attached location, including another partition, drive, or network storage. + + +#### Operation + +After running buildout to configure `collective.recipe.backup`, you'll find {file}`bin/backup` and {file}`bin/restore` scripts in your buildout directory. +Since all options are set via buildout, there are few command-line options, and operation is generally through bare commands. + +{file}`bin/restore` will accept a date-time argument, if you keep multiple backups. +For restore operations, stop Plone before starting your restore, and restart after the restore is complete. + +{file}`bin/backup` is commonly included in a cron table for regular operation. +You can run backup operations without stopping Plone. +Make sure you test your backup and restore process before you need it. + + +### Incremental backups + +`collective.recipe.backup` offers both incremental and full backups, and will maintain multiple versions of backups. +Tune these to meet your needs. + +When you enable incremental backups, the database packing operation will automatically cause the next backup to be a full backup. + +If your backup continuity need is critical, then your incremental backup schedule may need to be frequent. +Some Plone sites require incremental backups every few minutes. (upgrade-setup-a-test-environment-to-rehearse-the-upgrade-label)= -## Setup a test environment to rehearse the upgrade +## Set up a test environment to rehearse the upgrade ```{danger} Never work directly on your live site until you know that the upgrade was successful. diff --git a/docs/glossary.md b/docs/glossary.md index ed48c1423..be7bc554e 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -919,4 +919,8 @@ TDD - Write the functional code until the test passes. - Refactor both new and old code to make it well structured. +BLOB +Binary Large Object + A blob is a mass of data in binary form that does not necessarily conform to any file format. + ```