How to Back Up and Restore Forgejo: forgejo dump, the Database and an Off-Site Copy

Ellis Crowe

Ellis Crowe

November 20, 2026

How to Back Up and Restore Forgejo: forgejo dump, the Database and an Off-Site Copy

Your Forgejo instance started as a place to mirror a few repositories, and now it holds issues, pull request history, CI secrets, packages and the SSH keys of everyone who pushes to it. A disk failure or a botched upgrade would cost far more than the Git data, which most people have cloned somewhere anyway. This guide walks through backing up a Forgejo server in a way you can actually restore: what Forgejo stores and where, when forgejo dump is enough, how to dump the database properly, how to get a copy off the machine, and how to prove the whole thing works on a second instance.

Commands and paths here follow the Forgejo documentation for the current v17 release line. Forgejo’s own backup guide is the reference to keep open while you set this up, because your app.ini may move data away from the defaults.

Step 1: Map what a Forgejo server actually stores

Forgejo’s “Backups and Backup Restoration” page breaks an instance into a handful of parts. Before choosing a method, find where each one lives on your server:

  • The database. SQLite stores everything in one file at the path set by [database].PATH. PostgreSQL, MySQL and MariaDB keep data in their own servers, which need their own dump tools.
  • Git repositories. By default these sit in forgejo-repositories under the data directory of the work path. The docs note that [server].APP_DATA_PATH or [repository].ROOT can move them.
  • Storage. Attachments, LFS objects, avatars and packages are stored in local directories by default. If you configured S3-compatible (minio) storage instead, the docs say to rely on that system’s backups or copy the objects with a separate tool.
  • Queues and indexers. The default level queues and the bleve issue indexer live under data. Indexers can be rebuilt, so they are optional but convenient to keep.
  • Configuration. The whole app.ini file, plus any SSH host keys if Forgejo runs its built-in SSH server.

The configuration deserves special attention. Forgejo’s documentation calls out [security].SECRET_KEY (or the file referenced by SECRET_KEY_URI) as critical: without it, encrypted database values such as webhook credentials, Actions secrets, mirror credentials and two-factor settings become unreadable. Losing [oauth2].JWT_SECRET forces integrated systems to re-authenticate, and losing the SSH host keys makes every client complain about changed host keys. A database backup without the matching app.ini is a partial backup.

In the official Docker image, the Dockerfile sets GITEA_CUSTOM=/data/gitea, so app.ini lives at /data/gitea/conf/app.ini inside the container, and the whole /data volume holds the config, data and repositories. The rootless image mounts its data at /var/lib/gitea instead, according to Forgejo’s Docker installation docs. With SQLite and default settings, the backup guide notes that copying the data folder covers the database, repositories, storage, queues and indexers in one go.

Step 2: Decide how to keep the backup consistent

Forgejo’s backup guide is direct about this: “It is strongly recommended to shut down Forgejo during a backup.” A running instance may be writing to the database, a repository and the queue at the same moment, and a copy taken mid-write can restore into a state where they disagree.

The upgrade guide in earlier Forgejo docs (v11) described the options more fully. The most reliable backup is a synchronized point-in-time snapshot of all storage, such as a QEMU snapshot of a single VM disk holding everything, which can be taken while Forgejo runs. If data is spread across S3, an external PostgreSQL server and Redis, shutting Forgejo down during the backup is the only way to get a consistent state. Only in the simplest case, everything on one file system and an instance that is not busy, did that guide suggest forgejo dump on a running server.

For a small self-hosted instance, the practical choices are:

  1. Stop and copy. Stop the Forgejo container or service, dump the database, archive the data directory and app.ini, then start Forgejo again. Downtime is usually a minute or two.
  2. Snapshot. If Forgejo runs in a VM or on a file system with atomic snapshots, and the database is on the same volume, snapshot everything at once.
  3. forgejo dump on a quiet instance. Convenient, single-file, and good as an additional copy, with caveats covered next.

A plain document box on a closet shelf

Step 3: Run forgejo dump, and know its limits

The Forgejo CLI reference describes forgejo dump as a command that “compresses all related files and database into zip file.” Reading the command’s source shows what goes into the archive: app.ini, the custom directory, the data directory (including attachments, LFS and packages under data/), the repositories under repos, logs, and a SQL export of the database named forgejo-db.sql. The default output name is forgejo-dump-<unix timestamp>.zip.

The documented flags let you shape the archive:

  • --file / -f: output file name; - writes to standard output.
  • --type: zip by default, or tar, tar.gz, tar.xz, tar.bz2, tar.zst and a few others.
  • --tempdir / -t: where intermediate files are written.
  • --database / -d: SQL syntax for the export: sqlite3, mysql or postgres.
  • --skip-repository, --skip-log, --skip-custom-dir, --skip-lfs-data, --skip-attachment-data, --skip-package-data, --skip-index and --skip-repo-archives to leave parts out.
  • --verbose / -V or --quiet / -q, but not both.

On a bare-metal install, run the command as the user Forgejo runs as, pointing it at your config:

sudo -u git forgejo dump -c /etc/forgejo/app.ini --type tar.gz --file /var/backups/forgejo/forgejo-dump.tar.gz

Adjust the user and config path to your setup. In Docker, the official image creates a git user with UID 1000 and links the binary to /usr/local/bin/forgejo. The pattern from the upstream Gitea backup documentation, which Forgejo inherited, is to run docker exec as that user and inside a writable temporary directory so the archiving step does not fail on permissions:

docker exec -u git -w /tmp forgejo forgejo dump -c /data/gitea/conf/app.ini --type tar.gz --file /tmp/forgejo-dump.tar.gz

docker cp forgejo:/tmp/forgejo-dump.tar.gz /srv/backups/forgejo/

docker exec forgejo rm /tmp/forgejo-dump.tar.gz

Replace forgejo after -w /tmp with your container’s name. Running the dump as root instead of git is a common mistake that leaves files with the wrong owner.

Now the limits. Forgejo’s v11 upgrade guide warned that although the dump contains a copy of the database, “it has serious long standing open bugs that may introduce problems when re-injecting the SQL dump in a new database.” That guide recommended a native psql or mysql dump alongside it, and noted SQLite needs no separate dump because the database file itself is in the archive. The current backup page no longer mentions forgejo dump at all and describes file and database backups instead. Treat the dump as a convenient bundle of files, and rely on a native database dump for the database.

Step 4: Dump the database with its own tools

Forgejo’s backup guide names the right tool per engine: pg_dump for PostgreSQL, mysqldump for MySQL and mariadb-backup for MariaDB. For SQLite, it says to back up the file at [database].PATH.

SQLite

With Forgejo stopped, copying the database file is enough. If you prefer a consistent copy while it runs, SQLite’s online backup command works: sqlite3 /path/to/forgejo.db ".backup '/srv/backups/forgejo/forgejo.db'". Check [database].PATH in app.ini for the real file name rather than guessing.

PostgreSQL

With a typical Compose setup where the database service is called db, the database and role are forgejo, and you want PostgreSQL’s custom format:

docker compose exec -T db pg_dump -U forgejo -Fc forgejo > /srv/backups/forgejo/forgejo-db.dump

The -T flag disables the pseudo-terminal so the binary output is not mangled. Restore later with pg_restore into an empty database owned by the same role.

MySQL or MariaDB

For MySQL, mysqldump --single-transaction gives a consistent dump of InnoDB tables without locking them for the whole run. Make sure the dump uses utf8mb4, which the Gitea restore example also passes explicitly with --default-character-set=utf8mb4 when loading the SQL back.

If your instance runs SQLite, read backups that restore empty databases for why copying a live database file with a generic file backup tool is risky.

Step 5: Put it together in one script

For a Docker Compose install with PostgreSQL and the data bind-mounted at /srv/forgejo/data, a stop-and-copy backup script can be short:

  1. cd /srv/forgejo
  2. docker compose stop forgejo
  3. docker compose exec -T db pg_dump -U forgejo -Fc forgejo > /srv/backups/forgejo/forgejo-db-$(date +%F).dump
  4. tar -C /srv/forgejo -czf /srv/backups/forgejo/forgejo-data-$(date +%F).tar.gz data
  5. docker compose start forgejo

The database container keeps running while Forgejo is stopped, so the dump is taken while nothing is writing to it. The tarball contains app.ini, repositories, LFS objects, attachments, avatars, packages, queues and indexers, as long as you have not moved any of them outside /data. If you have, add those paths. Use set -e in the script and make sure Forgejo is started again even if a step fails, for example with a trap, so a failed backup does not become an outage.

Step 6: Schedule it with cron or a systemd timer

A nightly cron entry for root is the simplest option:

30 3 * * * /usr/local/sbin/forgejo-backup.sh >> /var/log/forgejo-backup.log 2>&1

A systemd timer adds logging through the journal and catches up on missed runs. Create forgejo-backup.service with Type=oneshot and ExecStart=/usr/local/sbin/forgejo-backup.sh, then forgejo-backup.timer with OnCalendar=*-*-* 03:30:00 and Persistent=true in its [Timer] section, and enable it with systemctl enable --now forgejo-backup.timer. Check the next run with systemctl list-timers.

Either way, add a failure alert. A backup job that silently stopped three months ago looks exactly like a working one until you need it. Pick a time when nobody is pushing and no scheduled mirrors or Actions workflows are expected to run, because the stop step interrupts them.

A server rack with green lights in a small closet

Step 7: Get a copy off the server

Backups on the same disk as Forgejo protect against mistakes, not hardware failure, theft or ransomware. Send the backup directory somewhere else after each run. Two common tools:

  • restic produces encrypted, deduplicated snapshots. After initializing a repository on a NAS, SFTP host or object storage, add restic -r <repository> backup /srv/backups/forgejo to the end of the script, followed by a retention rule such as restic -r <repository> forget --keep-daily 7 --keep-weekly 4 --prune. Store the restic password outside the server too, or the off-site copy is unreadable when you need it.
  • rclone copies files to dozens of cloud providers. rclone copy /srv/backups/forgejo remote:forgejo-backups uploads new files; wrap the remote in rclone’s crypt backend if the provider should not see the contents, since app.ini contains your secrets.

Then prune the local directory so it does not fill the disk. For a comparison of restic, Kopia, Borg and other options, see the best backup tools for a homelab.

Step 8: Restore Forgejo by hand

There is no forgejo restore command for a whole instance; the CLI’s restore-repo subcommand restores a single repository, which is a different job. Forgejo’s backup guide describes the full restore as a manual sequence:

  1. Restore the database using the engine’s own tool, or put the SQLite file back.
  2. Restore files as they were backed up, typically the whole data directory.
  3. Restore app.ini, or rebuild it so the paths point at the restored locations.
  4. Start Forgejo.

For the Compose example, that means stopping Forgejo, extracting the data tarball back to /srv/forgejo/data with ownership matching UID 1000, recreating an empty database and running pg_restore -U forgejo -d forgejo against the dump inside the database container, then starting Forgejo. Use the same Forgejo version that made the backup; upgrade only after the restore works.

After logging in as an administrator, the guide says to open /admin/monitor/cron and run the tasks that regenerate .ssh/authorized_keys and .ssh/authorized_principals, because the database is authoritative and those files are not part of the backup. The CLI equivalent for the keys file is forgejo admin regenerate keys. If you skipped the issue indexer, run the “Rebuild issue indexer” job; the repository indexer rebuilds on its own at startup. forgejo doctor check is documented as a way to “diagnose and optionally fix problems” if anything looks off.

Step 9: Prove it on a second instance

A backup you have never restored is a hypothesis. The safest test is a throwaway Forgejo on another machine or VM, using the same image tag as production:

  • Restore the database and data into it, following Step 8.
  • Before starting it, edit the restored app.ini: point ROOT_URL at the test hostname, and disable outgoing email under [mailer] so the copy does not send notifications to real users.
  • Keep it off networks where your Actions runners or webhooks receivers could reach it, so it does not pick up jobs or fire hooks meant for production.
  • Log in, open a few repositories, and check that recent commits, issues, pull requests, LFS files, attachments and avatars are all present.
  • Confirm that an Actions secret or mirror credential is readable, which proves SECRET_KEY came back correctly.
  • Clone over HTTPS and SSH, and time the whole process so you know how long a real recovery takes.

Repeat the test after major upgrades and whenever you change storage settings. If you are still moving projects in, migrating from GitHub to Forgejo is a good moment to set this up, because the first restore test will also confirm that migrated issues and pull requests survived.

More articles for you