From ab450f7e63010d03ce98508d25416d3d35157993 Mon Sep 17 00:00:00 2001
From: hiperman <patrykjaroszewski@proton.me>
Date: Fri, 28 Nov 2025 21:16:55 -0500
Subject: [PATCH] Add backup and restore docs

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 50 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index a1b0ae5..222c798 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,54 @@ The following playbook was tested on the latest Debian 12, it should work on Ubu
     gitea_protocol: http
     gitea_http_listen: '0.0.0.0'
 ```
+
+## Backup and Restore
+The backup system currently backs up all the data mounts and creates a compressed archive. The archive is stored on the remote machine at the directory given by `gitea_root_backup_dir`. The Ansible controller then downloads the archive and stores it at `gitea_local_backup_dir`.
+
+> ![NOTE]
+> The backup task stops the Compose stack to avoid data corruption. There will be a short downtime.
+
+### Creating a Backup
+To trigger a backup:
+```yaml
+---
+- name: Create Gitea backup
+  hosts: git.example.com
+  become: yes
+  tasks:
+    - name: Include gitea backup tasks
+      include_role:
+        name: gitea_docker
+        tasks_from: backup
+  vars:
+    gitea_root_backup_dir: '/opt/gitea/backups'
+    gitea_local_backup_dir: '~/backups/gitea'
+```
+
+> [!NOTE]
+> Currently backups only work with Gitea using `sqlite3`. `PostgresSQL` and `MySQL/MariaDB` are planned for a future release.
+
+### Restoring from Backup
+To restore from a backup, set the `gitea_restore_backup` variable to `true`. The tasks will use the latest backup in your backups directory on the Ansible controller. You may also specify a backup file to use with `gitea_backup_file`.
+
+> [!WARNING]
+> Restore operations will **completely replace** all existing Gitea data
+
+```yaml
+---
+- name: Restore Gitea from backup
+  hosts: git.example.com
+  become: yes
+  roles:
+    - role: gitea_docker
+  vars:
+    # Your defined variables
+    # ...
+
+    gitea_restore_backup: true
+    gitea_backup_file: '~/gitea-backups/gitea-backup-20240115-020000.tar.gz'  # Optional
+```
+
 # Variables
 
 ## Container Configuration
@@ -407,11 +455,9 @@ gitea_extra_config:
   
   # Git configuration
   GITEA__git__DISABLE_DIFF_HIGHLIGHT: "false"
-  GITEA__git_DOT_timeout__DEFAULT: "360"
+  GITEA__git__timeout__DEFAULT: "360"
 ```
 
-**Note:** When using `gitea_extra_config`, you must use the full Gitea environment variable format including the section name. Use `DOT` for periods in configuration keys.
-
 ### Finding Available Options
 
 For a complete list of available configuration options, refer to the official [Gitea Configuration Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet).
@@ -425,4 +471,4 @@ For a complete list of available configuration options, refer to the official [G
 3. **Validation**: The role does not validate extra configuration options. Ensure you're using valid Gitea configuration keys by consulting the official documentation.
 
 # License
-MIT License
\ No newline at end of file
+MIT License