docs: recommendations to ensure backup consistency and reliability (#19845) * docs: recommendations to ensure backup consistency and reliability * s/stooping/stopping/ * Update docs/content/doc/usage/backup-and-restore.en-us.md Co-authored-by: delvh <dev.lh@web.de> Co-authored-by: delvh <dev.lh@web.de>

Changes

1 changed files (+17/-0)

• docs/content/doc/usage/backup-and-restore.en-us.md
  • @@ -22,6 +22,12 @@ file can be unpacked and used to restore an instance.
    {{< toc >}} + ## Backup Consistency + + To ensure the consistency of the Gitea instance, it must be shutdown during backup. + + Gitea consists of a database, files and git repositories, all of which change when it is used. For instance, when a migration is in progress, a transaction is created in the database while the git repository is being copied over. If the backup happens in the middle of the migration, the git repository may be incomplete although the database claims otherwise because it was dumped afterwards. The only way to avoid such race conditions is by stopping the Gitea instance during the backups. + ## Backup Command (`dump`) Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
  • @@ -48,6 +54,17 @@ Inside the `gitea-dump-1482906742.zip` file, will be the following:
    Intermediate backup files are created in a temporary directory specified either with the `--tempdir` command-line parameter or the `TMPDIR` environment variable. + ## Backup the database + + The SQL dump created by `gitea dump` uses XORM and Gitea admins may prefer to use the native the MySQL and PostgreSQL dump tools instead. There are still open issues when using XORM for dumping the database that may cause problems when attempting to restore it. + + ```sh + # mysql + mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql + # postgres + pgdump -U $USER $DATABASE > gitea-db.sql + ``` + ### Using Docker (`dump`) There are a few caveats for using the `dump` command with Docker.