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