diff --git a/gitea_README.md b/gitea_README.md new file mode 100644 index 0000000..4059bae --- /dev/null +++ b/gitea_README.md @@ -0,0 +1,124 @@ +# Gitea + +> [!Note] +> The official backup and restore documentation for Gitea is located here - https://docs.gitea.com/administration/backup-and-restore. The steps below were taken from the official documentation and adapted to our local installation. + +# Backup Gitea + +> [!Warning] +> Do not simply copy raw database files or repository directories while Gitea is actively running. Doing so can cause corrupted database dumps or inconsistent repository states. Always use Gitea's built-in `gitea dump` utility to generate a consistent snapshot. + +## Automated Backup (Recommended) + +Run the automated backup script to trigger the dump, copy the archive to the backup drive, and prune old retention: + +```bash +sudo /srv/docker/gitea/gitea_backup.sh +``` + +## Manual Backup + +If you need to perform a manual backup without running the script: + +### 1. Generate Dump File +Run the internal `gitea dump` command inside the container: + +```bash +sudo docker exec -u git -w /tmp gitea bash -c '/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini -f /data/gitea-dump.zip' +``` + +### 2. Copy Archive to Backup Destination +Copy the generated zip archive to your desired backup directory and clean up the staging file: + +```bash +# Define target directory +TARGET_DIR="/mnt/5TB-Disk1/backup/services/gitea/manual_$(date +%Y-%m-%d)" +mkdir -p "$TARGET_DIR" + +# Rsync zip archive to backup location +sudo rsync -av --no-owner --no-group /srv/docker/gitea/data/gitea-dump.zip "$TARGET_DIR/gitea-dump.zip" + +# Clean up temporary staging archive on host source +sudo rm -f /srv/docker/gitea/data/gitea-dump.zip +``` + +--- + +# Restore Gitea + +> [!Caution] +> Always stop the Gitea container prior to restoring data to avoid database file conflicts or repository corruption. + +## Restore Procedure + +### 1. Identify Backup File +Check `latest.txt` or list the backup directory to identify the backup archive you want to restore: + +```bash +# View path to the most recent successful backup directory +cat /mnt/5TB-Disk1/backup/services/gitea/latest.txt + +# Or list all available backups +ls -l /mnt/5TB-Disk1/backup/services/gitea/ +``` + +### 2. Stop Gitea Container +Stop the running service: + +```bash +sudo docker stop gitea +# OR if using docker compose: +# cd /srv/docker/gitea && sudo docker compose down +``` + +### 3. Extract Backup Archive +Create a temporary working directory and extract `gitea-dump.zip`: + +```bash +# Create temporary extraction directory +mkdir -p /tmp/gitea-restore +unzip /mnt/5TB-Disk1/backup/services/gitea/backup_2026-10-03_110000/gitea-dump.zip -d /tmp/gitea-restore +``` + +### 4. Restore Configuration and Data +Copy extracted configuration files, data, and repositories back to the host Gitea data volume: + +```bash +# Restore configuration file +sudo cp -r /tmp/gitea-restore/app.ini /srv/docker/gitea/data/gitea/conf/app.ini + +# Restore repositories, attachments, avatars, and data assets +sudo cp -r /tmp/gitea-restore/repos/* /srv/docker/gitea/data/git/repositories/ 2>/dev/null || true +sudo cp -r /tmp/gitea-restore/data/* /srv/docker/gitea/data/gitea/ + +# Clean up temporary extraction folder +rm -rf /tmp/gitea-restore +``` + +> [!Note] +> If using SQLite (default database inside `/data/gitea/gitea.db`), copying `/tmp/gitea-restore/data/*` restores the SQLite database directly. If using MySQL or PostgreSQL, import `gitea-db.sql` directly into your database service instead (`docker exec -i mysql ... < gitea-db.sql`). + +### 5. Verify Ownership and Permissions +Ensure the `git` user (UID/GID `1000:1000`) owns all restored files: + +```bash +sudo chown -R 1000:1000 /srv/docker/gitea/data +``` + +### 6. Start Gitea Container +Restart the Gitea service and inspect container logs: + +```bash +sudo docker start gitea +# OR if using docker compose: +# cd /srv/docker/gitea && sudo docker compose up -d + +# Verify container logs +sudo docker logs -f gitea +``` + +--- + +## Authors and Acknowledgment +* **Gitea Documentation**: https://docs.gitea.com/administration/backup-and-restore +* **Gitea Repository**: https://github.com/go-gitea/gitea \ No newline at end of file