Backups and upgrades
Gitea Mirror keeps everything in one data directory. Back that up, keep your two secrets, and an upgrade or a move to a new machine is a matter of copying the directory back.
Where the data lives
| Install | Data directory |
|---|---|
| Docker and Docker Compose | /app/data in the container, usually the ./data folder or a named volume on the host |
| Helm | The PersistentVolumeClaim mounted at /app/data |
| NixOS module | dataDir, /var/lib/gitea-mirror by default |
nix run |
~/.local/share/gitea-mirror, or DATA_DIR |
| Bare metal | data/ in the folder you start it from |
What is inside is listed in Deployment.
What to back up
- The data directory.
tmp/can be left out, and so can.workdir/in a Nix install, which is rebuilt on every start.mirrors/can be left out too: a missing clone for a GitHub or GitLab destination is cloned again on its next sync, at the cost of a full download. - Your secrets, if you set them yourself. When you let the app generate them, they are in the data directory as
.better_auth_secretand.encryption_secret. When you setBETTER_AUTH_SECRETandENCRYPTION_SECRETin a.envfile, a compose file, a Kubernetes Secret or a NixOSenvironmentFile, back that up as well.
Without the same ENCRYPTION_SECRET, every stored token is unreadable and has to be entered again. Without the same BETTER_AUTH_SECRET, everyone is signed out.
The mirrors themselves live on your Gitea or Forgejo server and are backed up with it, not here.
Taking a backup
The simplest safe backup is to stop the app, copy the directory and start it again:
docker compose stop
tar czf gitea-mirror-backup.tar.gz data
docker compose start
That is for the quick start compose file, which keeps the data in ./data next to it. docker-compose.yml uses a named volume instead; copy it out with a throwaway container while the app is stopped:
docker run --rm -v gitea-mirror_gitea-mirror-data:/data -v "$PWD":/backup alpine \
tar czf /backup/gitea-mirror-backup.tar.gz -C /data .
Compose puts the project name, usually the folder name, in front of the volume name. docker volume ls shows the exact name.
Copying the database file while the app is writing to it can catch a write halfway. To back up without stopping, let SQLite make the copy. The Docker image includes the sqlite3 tool:
docker compose exec gitea-mirror sqlite3 /app/data/gitea-mirror.db ".backup '/app/data/gitea-mirror-backup.db'"
Then copy gitea-mirror-backup.db off the machine together with the rest of the directory. On bare metal, run the same sqlite3 command against data/gitea-mirror.db.
Restoring
- Stop the app.
- Put the data directory back where it was, owned by the user the app runs as.
- Start the app with the same secrets.
If you used the online backup, rename gitea-mirror-backup.db to gitea-mirror.db first. On first start the app applies any database migrations the restored copy is missing, so a backup from an older version restores fine into a newer one.
The same steps move an install to another method, because the database and any generated secrets live in the data directory. For example, to move from Docker to NixOS, copy the contents of the data volume into dataDir and run chown -R gitea-mirror:gitea-mirror on it before starting the service.
Upgrading
Back up first, and read the release notes for anything marked as a change in behavior. Database migrations run on their own when the new version starts.
Docker Compose:
docker compose pull
docker compose up -d
docker compose up -d alone keeps the image you already have.
Plain docker run: docker pull ghcr.io/raylabshq/gitea-mirror:latest, then remove the container and run it again with the same flags and the same data volume.
Helm: run the same helm upgrade --install command you installed with. Without --version it moves to the newest chart.
NixOS: update the flake input, then rebuild:
nix flake update gitea-mirror
sudo nixos-rebuild switch
Proxmox LXC: the Community Scripts installer has its own update command; see the Community Scripts page.
Bare metal:
git pull
bun install
bun run build
Then restart the app (bun run start, or your systemd service).
Going back
Downgrades are not tested. If an upgrade goes wrong, start the version you had before and restore the backup you took before upgrading.
Pinning a version
latest follows the newest stable release. To update only when you choose, pin a release tag instead:
| Tag | What it is |
|---|---|
latest |
The newest stable release. Pre-releases do not move it. |
v3.53.1 |
One release. Every release has its own tag. |
edge |
Every commit to main, including unreleased changes. |
services:
gitea-mirror:
image: ghcr.io/raylabshq/gitea-mirror:v3.53.1
With Helm, pin the chart with --version. With Nix, use github:RayLabsHQ/gitea-mirror/v3.53.1 as the flake reference.
Knowing when there is an update
The running version is shown at the bottom of the sidebar, with a line underneath when a newer release is out. The same information is in /api/health as version, latestVersion and updateAvailable, which suits monitoring tools.
