2017-11-27 05:44:32 +08:00
---
date: "2017-01-01T16:00:00+02:00"
title: "Usage: Backup and Restore"
slug: "backup-and-restore"
weight: 11
2020-12-09 14:47:06 +08:00
toc: false
2017-11-27 05:44:32 +08:00
draft: false
menu:
sidebar:
parent: "usage"
name: "Backup and Restore"
weight: 11
identifier: "backup-and-restore"
---
# Backup and Restore
2021-12-24 11:56:57 +08:00
Gitea currently has a `dump` command that will save the installation to a ZIP file. This
2018-01-09 06:48:42 +08:00
file can be unpacked and used to restore an instance.
2017-11-27 05:44:32 +08:00
2020-12-09 14:47:06 +08:00
**Table of Contents**
{{< toc > }}
2017-11-27 05:44:32 +08:00
## Backup Command (`dump`)
2019-04-10 21:34:44 +08:00
Switch to the user running Gitea: `su git` . Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
2018-01-09 06:48:42 +08:00
directory. There should be some output similar to the following:
2017-11-27 05:44:32 +08:00
2019-04-10 21:34:44 +08:00
```none
2017-11-27 05:44:32 +08:00
2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
2016/12/27 22:32:22 Dumping database...
2016/12/27 22:32:22 Packing dump files...
2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
```
2018-01-09 06:48:42 +08:00
Inside the `gitea-dump-1482906742.zip` file, will be the following:
2017-11-27 05:44:32 +08:00
2020-12-09 14:47:06 +08:00
- `app.ini` - Optional copy of configuration file if originally stored outside of the default `custom/` directory
- `custom` - All config or customization files in `custom/` .
2021-12-24 11:56:57 +08:00
- `data` - Data directory in < GITEA_WORK_DIR > , except sessions if you are using file session. This directory includes `attachments` , `avatars` , `lfs` , `indexers` , SQLite file if you are using SQLite.
2020-12-09 14:47:06 +08:00
- `gitea-db.sql` - SQL dump of database
- `gitea-repo.zip` - Complete copy of the repository directory.
- `log/` - Various logs. They are not needed for a recovery or migration.
2017-11-27 05:44:32 +08:00
2018-01-09 06:48:42 +08:00
Intermediate backup files are created in a temporary directory specified either with the
`--tempdir` command-line parameter or the `TMPDIR` environment variable.
2017-11-27 05:44:32 +08:00
2019-04-08 20:45:29 +08:00
### Using Docker (`dump`)
2019-04-10 21:34:44 +08:00
2019-04-08 20:45:29 +08:00
There are a few caveats for using the `dump` command with Docker.
The command has to be executed with the `RUN_USER = <OS_USERNAME>` specified in `gitea/conf/app.ini` ; and, for the zipping of the backup folder to occur without permission error the command `docker exec` must be executed inside of the `--tempdir` .
Example:
2019-04-10 21:34:44 +08:00
```none
2022-05-24 14:57:15 +08:00
docker exec -u < OS_USERNAME > -it -w < --tempdir > $(docker ps -qf 'name=^< NAME_OF_DOCKER_CONTAINER > $') bash -c '/user/local/bin/gitea dump -c < /path/to/app.ini>'
2019-04-10 21:34:44 +08:00
```
2019-04-08 20:45:29 +08:00
2020-12-09 14:47:06 +08:00
\*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir` , then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly.
2019-04-08 20:45:29 +08:00
The result should be a file, stored in the `--tempdir` specified, along the lines of: `gitea-dump-1482906742.zip`
2017-11-27 05:44:32 +08:00
## Restore Command (`restore`)
2018-01-09 06:48:42 +08:00
There is currently no support for a recovery command. It is a manual process that mostly
involves moving files to their correct locations and restoring a database dump.
Example:
2019-04-10 21:34:44 +08:00
2020-12-09 14:47:06 +08:00
```sh
2021-01-19 10:05:11 +08:00
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
mv data/conf/app.ini /etc/gitea/conf/app.ini
mv data/* /var/lib/gitea/data/
mv log/* /var/lib/gitea/log/
mv repos/* /var/lib/gitea/repositories/
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
# mysql
2020-04-14 10:55:20 +08:00
mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE < gitea-db.sql
2021-01-19 10:05:11 +08:00
# sqlite3
sqlite3 $DATABASE_PATH < gitea-db.sql
# postgres
psql -U $USER -d $DATABASE < gitea-db.sql
2018-01-09 06:48:42 +08:00
service gitea restart
```
2019-09-15 10:37:09 +08:00
2021-12-24 11:56:57 +08:00
Repository Git Hooks should be regenerated if installation method is changed (eg. binary -> Docker), or if Gitea is installed to a different directory than the previous installation.
2019-09-15 10:37:09 +08:00
With Gitea running, and from the directory Gitea's binary is located, execute: `./gitea admin regenerate hooks`
2021-12-24 11:56:57 +08:00
This ensures that application and configuration file paths in repository Git Hooks are consistent and applicable to the current installation. If these paths are not updated, repository `push` actions will fail.
2022-03-03 00:20:00 +08:00
### Using Docker (`restore`)
There is also no support for a recovery command in a Docker-based gitea instance. The restore process contains the same steps as described in the previous section but with different paths.
Example:
```sh
# open bash session in container
docker exec --user git -it 2a83b293548e bash
# unzip your backup file within the container
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
# restore the gitea data
mv data/* /data/gitea
# restore the repositories itself
mv repos/* /data/git/repositories/
# adjust file permissions
chown -R git:git /data
# Regenerate Git Hooks
/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
```
The default user in the gitea container is `git` (1000:1000). Please replace `2a83b293548e` with your gitea container id or name.
These are the default paths used in the container:
```text
DEFAULT CONFIGURATION:
CustomPath: /data/gitea (GITEA_CUSTOM)
CustomConf: /data/gitea/conf/app.ini
AppPath: /usr/local/bin/gitea
AppWorkPath: /usr/local/bin
```
### Using Docker-rootless (`restore`)
The restore workflow in Docker-rootless containers differs only in the directories to be used:
```sh
# open bash session in container
docker exec --user git -it 2a83b293548e bash
# unzip your backup file within the container
unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662
# restore the app.ini
mv data/conf/app.ini /etc/gitea/app.ini
# restore the gitea data
mv data/* /var/lib/gitea
# restore the repositories itself
mv repos/* /var/lib/gitea/git/repositories
# adjust file permissions
chown -R git:git /etc/gitea/app.ini /var/lib/gitea
# Regenerate Git Hooks
/usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
```