mirror of
https://github.com/RayLabsHQ/gitea-mirror.git
synced 2026-08-09 18:32:46 +02:00
docs(www): fix inaccurate claims in use-case and comparison pages
- Remove references to nonexistent /api/export and /api/repos/:id/logs endpoints - Correct storage model: mirrored repos and LFS live in Gitea, not the data/ volume - Fix default sync interval (daily, not 1 hour) and startup log line - Add write:organization to required Gitea token scopes - Remove nonexistent metrics endpoint and per-repo interval claims from Helm page - Fix rate-limit advice (limits are per account, not per IP/token) - Refresh stale comparison content (outage dates, BackHub/Rewind acquisition) - Add missing git clone step to comparison quick start
This commit is contained in:
Arunavo Ray
@@ -11,7 +11,7 @@ canonical: "https://gitea-mirror.raylabs.io/comparison/github-backup-tools/"
|
||||
|
||||
GitHub hosts millions of repositories, but relying on a single platform comes with risks:
|
||||
|
||||
- **Outages**: GitHub experiences downtime (most recent: November 2024, October 2024, August 2024)
|
||||
- **Outages**: GitHub experiences downtime several times a year (check [githubstatus.com](https://www.githubstatus.com/history) for the running history)
|
||||
- **Account issues**: DMCA takedowns, TOS violations, or account suspensions can lock you out
|
||||
- **Accidental deletions**: One wrong click and your repo history vanishes
|
||||
- **Company changes**: Microsoft's acquisition led to policy shifts many developers disagreed with
|
||||
@@ -64,6 +64,8 @@ The question isn't *if* you need backups—it's *which solution* fits your workf
|
||||
|
||||
**Setup**:
|
||||
```bash
|
||||
git clone https://github.com/RayLabsHQ/gitea-mirror.git
|
||||
cd gitea-mirror
|
||||
docker compose -f docker-compose.alt.yml up -d
|
||||
# Visit http://localhost:4321, create account, add tokens
|
||||
```
|
||||
@@ -72,7 +74,7 @@ docker compose -f docker-compose.alt.yml up -d
|
||||
|
||||
**Best for**: Teams wanting zero infrastructure management, compliance-focused organizations
|
||||
|
||||
**How it works**: SaaS platform that backs up GitHub orgs/repos to their cloud storage. Offers point-in-time recovery and compliance features.
|
||||
**How it works**: SaaS platform that backs up GitHub orgs/repos to their cloud storage. Offers point-in-time recovery and compliance features. Note: BackHub was acquired by Rewind and now operates as part of Rewind's backup lineup.
|
||||
|
||||
**Pros**:
|
||||
- ✅ Fully managed (zero infrastructure)
|
||||
@@ -237,7 +239,7 @@ Yes! The Docker setup takes 15 minutes. Test with a few repos, evaluate, then sc
|
||||
|
||||
### Does Gitea Mirror work with GitHub Enterprise Cloud?
|
||||
|
||||
Yes, as long as you have API access and a personal access token. The GitHub API endpoint is configurable.
|
||||
Yes. GitHub Enterprise Cloud uses the standard github.com API, so a personal access token is all you need. For GitHub Enterprise Server, point the mirror at your instance's API with the `GH_API_URL` environment variable.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
@@ -37,17 +37,17 @@ docker compose -f docker-compose.alt.yml ps
|
||||
docker compose -f docker-compose.alt.yml logs -f gitea-mirror
|
||||
```
|
||||
|
||||
Wait for "Server started" before moving on.
|
||||
Wait for the `Runtime server listening` line in the logs before moving on.
|
||||
|
||||
### 2. Generate tokens and connect GitHub
|
||||
|
||||
1. Create a GitHub personal access token (classic) with `repo` enabled and, inside the `admin:org` section, check `read:org` so the mirror can list organization repositories—leave `write:org` and `admin:org` unchecked.
|
||||
2. Log in to Gitea and create an access token for an admin/owner account with `write:repository`.
|
||||
2. Log in to Gitea and create an access token for an admin/owner account with `write:repository` and `write:organization` (the second scope lets the mirror create destination organizations).
|
||||
3. Visit `http://<host>:4321` and sign up—the first user becomes admin.
|
||||
4. Complete the setup wizard:
|
||||
- Paste the GitHub PAT and Gitea URL/token.
|
||||
- Choose which GitHub owners (user/org) to track.
|
||||
- Leave sync interval at the default 1 hour to start.
|
||||
- Leave the sync interval at the default (daily) to start; you can shorten it later.
|
||||
|
||||
### 3. Stage your first backup job
|
||||
|
||||
@@ -92,7 +92,7 @@ Treat the mirror like any other DR asset:
|
||||
|
||||
- The container exposes `/api/health`; add it to Uptime Kuma, Healthchecks.io, or Prometheus.
|
||||
- Mirror failures surface in the activity log; consider exporting them through the `/api/events` endpoint.
|
||||
- Watch the `data/` volume on the host (e.g. `du -sh data/`) to make sure you have headroom for mirrored repos and LFS blobs.
|
||||
- Watch disk usage on your Gitea host—that's where the mirrored repos and LFS blobs actually live. Gitea Mirror's own `data/` volume stays small (SQLite database plus optional pre-sync backup bundles).
|
||||
|
||||
## Hardening tips
|
||||
|
||||
@@ -117,4 +117,4 @@ Most homelabs pick 30–120 minutes. Faster schedules improve RPO but use more G
|
||||
|
||||
### Where are backups stored and how do I restore?
|
||||
|
||||
Repositories and the SQLite DB live under the `data/` directory (or your configured volume). Restore by cloning from Gitea or by moving the volume to a fresh deployment and signing back in.
|
||||
The mirrored repositories live in your Gitea instance's storage—Gitea does the actual mirroring. Gitea Mirror's `data/` directory holds its SQLite database (configuration, job history) and optional pre-sync backup bundles. Restore code by cloning from Gitea; restore the mirror service by moving the `data/` volume to a fresh deployment and signing back in.
|
||||
|
||||
@@ -99,21 +99,20 @@ kubectl -n gitea-mirror get pods,svc,pvc
|
||||
kubectl -n gitea-mirror logs deploy/gitea-mirror --tail=100
|
||||
```
|
||||
|
||||
Watch for `Server started` in the logs. Once ready, browse to the ingress host (or userland port-forward with `kubectl port-forward svc/gitea-mirror 4321:4321`). Complete the first-run wizard just like the Docker playbook.
|
||||
Watch for the `Runtime server listening` line in the logs. Once ready, browse to the ingress host (or userland port-forward with `kubectl port-forward svc/gitea-mirror 4321:4321`). Complete the first-run wizard just like the Docker playbook.
|
||||
|
||||
After the pod is healthy, open **Configuration → Connections** inside the UI to add GitHub owners, choose a destination strategy, and enable metadata/LFS mirroring.
|
||||
|
||||
### 4. Keep it updated
|
||||
|
||||
- Pull chart updates when you bump the repo: `git pull` then re-run the `helm upgrade` command.
|
||||
- Override the container image tag with `--set image.tag=v3.7.2` if you need to pin (defaults to `v{appVersion}` from Chart.yaml).
|
||||
- Override the container image tag with `--set image.tag=v3.21.0` if you need to pin a release (defaults to `v{appVersion}` from Chart.yaml).
|
||||
- Use Helm rollbacks if a release misbehaves: `helm rollback gitea-mirror <REVISION> -n gitea-mirror`.
|
||||
|
||||
## Observability
|
||||
|
||||
- Attach the `/api/health` endpoint to your cluster’s probing (Kubernetes probes are already configured by the chart).
|
||||
- Expose the metrics endpoint via a `ServiceMonitor` if you run Prometheus; add `extraAnnotations` to make it discoverable.
|
||||
- Watch PVC growth with `kubectl df-pv` or your storage dashboard to ensure LFS blobs do not exhaust the volume.
|
||||
- Attach the `/api/health` endpoint to your cluster’s probing (Kubernetes probes are already configured by the chart); external monitors like Uptime Kuma or Blackbox Exporter can poll it too.
|
||||
- Watch PVC growth with `kubectl df-pv` or your storage dashboard—the volume holds the SQLite database and any pre-sync backup bundles.
|
||||
|
||||
## Disaster-recovery drill
|
||||
|
||||
@@ -145,4 +144,4 @@ Yes. Leave `existingSecret` empty and the chart will create a secret with the va
|
||||
|
||||
### How do I throttle syncs to fit my quota?
|
||||
|
||||
Adjust `gitea-mirror.automation.schedule_interval` in your values file (default: 3600 seconds = 1 hour). Lower values mean more frequent syncs; higher values create quieter schedules. You can also configure intervals per owner/repository inside the web UI.
|
||||
Adjust `gitea-mirror.automation.schedule_interval` in your values file (default: 3600 seconds = 1 hour). Lower values mean more frequent syncs; higher values create quieter schedules. You can also change the interval later from **Configuration → Automation** in the web UI.
|
||||
|
||||
@@ -41,7 +41,7 @@ Shell scripts and `git clone --mirror` jobs work until they don’t—usually wh
|
||||
|
||||
- Point your monitoring system at `http://<mirror-host>:4321/api/health` to track uptime.
|
||||
- Review sync failures from the **Activity Log** page or export them via `/api/events` for long-term retention.
|
||||
- Run `bun run manage-db check` during maintenance windows to verify background tasks, migrations, and queue state.
|
||||
- Run `bun run manage-db check` during maintenance windows to verify the database and migrations are healthy.
|
||||
|
||||
<figure class="mt-8 flex flex-col items-center">
|
||||
<img
|
||||
@@ -59,7 +59,7 @@ Shell scripts and `git clone --mirror` jobs work until they don’t—usually wh
|
||||
|
||||
- Store GitHub and Gitea tokens via the Configuration UI—Gitea Mirror encrypts them at rest.
|
||||
- Rotate tokens on a schedule and note expiry dates in your homelab runbook; the dashboard surfaces failures when credentials expire.
|
||||
- Export the configuration JSON (`/api/export`) alongside your documentation so you can rebuild the mirror quickly if you need to redeploy.
|
||||
- Back up the `data/` directory alongside your documentation—the SQLite database holds your configuration, so restoring it rebuilds the mirror quickly if you need to redeploy.
|
||||
|
||||
## Validate automation
|
||||
|
||||
|
||||
@@ -55,8 +55,8 @@ In **Configuration → Connections**, open **Content & Data**:
|
||||
### 4. Record provenance
|
||||
|
||||
- Add a README or label inside the archive organization that captures the upstream URL, first mirrored date, and token owner.
|
||||
- Export a CSV from the **Repositories** view or hit `/api/events` quarterly so you retain a human-friendly change log.
|
||||
- Store the configuration export (`/api/export`) alongside your disaster-recovery docs in case you need to rebuild the service.
|
||||
- Export the **Activity Log** as CSV or hit `/api/events` quarterly so you retain a human-friendly change log.
|
||||
- Back up the `data/` directory (the SQLite database holds your configuration) alongside your disaster-recovery docs in case you need to rebuild the service.
|
||||
|
||||
### 5. Back up the backup
|
||||
|
||||
@@ -66,7 +66,7 @@ In **Configuration → Connections**, open **Content & Data**:
|
||||
|
||||
## Verify the archive
|
||||
|
||||
1. Delete a draft issue on GitHub.
|
||||
1. Delete a test issue on GitHub.
|
||||
2. Wait for the next sync; open the issue in Gitea—you should still see the original content.
|
||||
3. Compare `git tag -l` in both remotes to ensure releases match.
|
||||
4. Use `git lfs ls-files` to confirm large assets made it across.
|
||||
|
||||
@@ -56,7 +56,7 @@ systemctl status gitea-mirror
|
||||
ls /opt/gitea-mirror/data
|
||||
```
|
||||
|
||||
You should see `gitea-mirror.db` and a `repos/` directory. Data lives under `/opt/gitea-mirror/data`; back it up or snapshot the underlying storage pool regularly.
|
||||
You should see `gitea-mirror.db` (and a `repo-backups/` directory once pre-sync backups run). Data lives under `/opt/gitea-mirror/data`; back it up or snapshot the underlying storage pool regularly. The mirrored repositories themselves live on your Gitea server.
|
||||
|
||||
### 4. Expose the service (optional)
|
||||
|
||||
|
||||
@@ -69,13 +69,13 @@ In **Configuration → Connections → Content & Data**:
|
||||
|
||||
- Watch the **Activity Log** for failed runs and retry jobs; filter by repository when you need to chase a single mirror.
|
||||
- Point Healthchecks.io, Uptime Kuma, or Prometheus at `http://<mirror-host>:4321/api/health` to confirm the service stays responsive.
|
||||
- Export `/api/repos/:id/logs` or the global `/api/events` endpoint periodically to archive sync history alongside the repositories themselves.
|
||||
- Export the `/api/events` endpoint (or the Activity Log CSV) periodically to archive sync history alongside the repositories themselves.
|
||||
|
||||
## Tips for smooth syncing
|
||||
|
||||
- Avoid running more than one mirror against the same Gitea target; let Gitea Mirror manage the schedule centrally.
|
||||
- When restructuring orgs, temporarily disable automatic syncing, move repos in Gitea, then re-enable the scheduler to avoid churn.
|
||||
- Rate limits cropping up? Move the mirror onto a different IP or configure GitHub fine-grained PATs per org.
|
||||
- Rate limits cropping up? Lengthen the sync interval or trim the metadata components you mirror—authenticated GitHub rate limits are per account, so extra tokens from the same user won't raise the ceiling.
|
||||
|
||||
## Related playbooks
|
||||
|
||||
|
||||
Reference in New Issue
Block a user