media-server/gitea_README.md

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:

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:

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:

# 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:

# 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:

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:

# 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:

# 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 <db_container> mysql ... < gitea-db.sql).

5. Verify Ownership and Permissions

Ensure the git user (UID/GID 1000:1000) owns all restored files:

sudo chown -R 1000:1000 /srv/docker/gitea/data

6. Start Gitea Container

Restart the Gitea service and inspect container logs:

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