2021-09-09 18:13:21 +00:00
---
date: "2021-09-02T16:00:00+08:00"
title: "Upgrade from an old Gitea"
slug: "upgrade-from-gitea"
weight: 10
toc: false
draft: false
menu:
sidebar:
2023-03-23 20:44:09 +00:00
parent: "installation"
name: "Upgrade From Old Gitea"
weight: 100
2021-09-09 18:13:21 +00:00
identifier: "upgrade-from-gitea"
---
# Upgrade from an old Gitea
**Table of Contents**
{{< toc > }}
To update Gitea, download a newer version, stop the old one, perform a backup, and run the new one.
2022-07-28 01:22:47 +00:00
Every time a Gitea instance starts up, it checks whether a database migration should be run.
2021-09-09 18:13:21 +00:00
If a database migration is required, Gitea will take some time to complete the upgrade and then serve.
2022-08-05 14:20:13 +00:00
## Check the Changelog for breaking changes
To make Gitea better, some breaking changes are unavoidable, especially for big milestone releases.
Before upgrade, please read the [Changelog on Gitea blog ](https://blog.gitea.io/ )
and check whether the breaking changes affect your Gitea instance.
2021-09-09 18:13:21 +00:00
## Backup for downgrade
2022-07-28 01:22:47 +00:00
Gitea keeps compatibility for patch versions whose first two fields are the same (`a.b.x` -> `a.b.y` ),
these patch versions can be upgraded and downgraded with the same database structure.
Otherwise (`a.b.?` -> `a.c.?` ), a newer Gitea version will upgrade the old database
2021-09-09 18:13:21 +00:00
to a new structure that may differ from the old version.
For example:
| From | To | Result |
| --- | --- | --- |
| 1.4.0 | 1.4.1 | ✅ |
| 1.4.1 | 1.4.0 | ⚠️ Not recommended, take your own risk! Although it may work if the database structure doesn't change, it's highly recommended to use a backup to downgrade. |
| 1.4.x | 1.5.y | ✅ Database gets upgraded. You can upgrade from 1.4.x to the latest 1.5.y directly. |
| 1.5.y | 1.4.x | ❌ Database already got upgraded and can not be used for an old Gitea, use a backup to downgrade. |
2022-07-28 01:22:47 +00:00
**Since you can not run an old Gitea with an upgraded database,
a backup should always be made before a database upgrade.**
2021-09-09 18:13:21 +00:00
If you use Gitea in production, it's always highly recommended to make a backup before upgrade,
even if the upgrade is between patch versions.
Backup steps:
* Stop Gitea instance
* Backup database
* Backup Gitea config
* Backup Gitea data files in `APP_DATA_PATH`
* Backup Gitea external storage (eg: S3/MinIO or other storages if used)
If you are using cloud services or filesystems with snapshot feature,
a snapshot for the Gitea data volume and related object storage is more convenient.
## Upgrade with Docker
* `docker pull` the latest Gitea release.
* Stop the running instance, backup data.
* Use `docker` or `docker-compose` to start the newer Gitea Docker container.
## Upgrade from package
* Stop the running instance, backup data.
* Use your package manager to upgrade Gitea to the latest version.
* Start the Gitea instance.
## Upgrade from binary
* Download the latest Gitea binary to a temporary directory.
* Stop the running instance, backup data.
2022-07-28 01:22:47 +00:00
* Replace the installed Gitea binary with the downloaded one.
2021-09-09 18:13:21 +00:00
* Start the Gitea instance.
2022-02-06 20:07:52 +00:00
A script automating these steps for a deployment on Linux can be found at [`contrib/upgrade.sh` in Gitea's source tree ](https://github.com/go-gitea/gitea/blob/main/contrib/upgrade.sh ).
2021-09-09 18:13:21 +00:00
## Take care about customized templates
2022-07-28 01:22:47 +00:00
Gitea's template structure and variables may change between releases, if you are using customized templates,
do pay attention if your templates are compatible with the Gitea you are using.
2021-09-09 18:13:21 +00:00
2022-07-28 01:22:47 +00:00
If the customized templates don't match Gitea version, you may experience:
`50x` server error, page components missing or malfunctioning, strange page layout, ...
2021-09-09 18:13:21 +00:00
Remove or update the incompatible templates and Gitea web will work again.
