2021-09-09 14:13:21 -04:00
---
date: "2021-09-02T16:00:00+08:00"
title: "Upgrade from an old Gitea"
slug: "upgrade-from-gitea"
2023-07-26 00:53:13 -04:00
sidebar_position: 100
2021-09-09 14:13:21 -04:00
toc: false
draft: false
Refactor docs (#23752)
This was intended to be a small followup for
https://github.com/go-gitea/gitea/pull/23712, but...here we are.
1. Our docs currently use `slug` as the entire URL, which makes
refactoring tricky (see https://github.com/go-gitea/gitea/pull/23712).
Instead, this PR attempts to make future refactoring easier by using
slugs as an extension of the section. (Hugo terminology)
- What the above boils down to is this PR attempts to use directory
organization as URL management. e.g. `usage/comparison.en-us.md` ->
`en-us/usage/comparison/`, `usage/packages/overview.en-us.md` ->
`en-us/usage/packages/overview/`
- Technically we could even remove `slug`, as Hugo defaults to using
filename, however at least with this PR it means `slug` only needs to be
the name for the **current file** rather than an entire URL
2. This PR adds appropriate aliases (redirects) for pages, so anything
on the internet that links to our docs should hopefully not break.
3. A minor nit I've had for a while, renaming `seek-help` to `support`.
It's a minor thing, but `seek-help` has a strange connotation to it.
4. The commits are split such that you can review the first which is the
"actual" change, and the second is added redirects so that the first
doesn't break links elsewhere.
---------
Signed-off-by: jolheiser <john.olheiser@gmail.com>
2023-04-27 23:33:41 -04:00
aliases:
- /en-us/upgrade-from-gitea
2021-09-09 14:13:21 -04:00
menu:
sidebar:
2023-03-23 11:18:24 -04:00
parent: "installation"
name: "Upgrade From Old Gitea"
2023-07-26 00:53:13 -04:00
sidebar_position: 100
2021-09-09 14:13:21 -04:00
identifier: "upgrade-from-gitea"
---
# Upgrade from an old Gitea
To update Gitea, download a newer version, stop the old one, perform a backup, and run the new one.
2022-07-27 21:22:47 -04:00
Every time a Gitea instance starts up, it checks whether a database migration should be run.
2021-09-09 14:13:21 -04:00
If a database migration is required, Gitea will take some time to complete the upgrade and then serve.
2022-08-05 10:20:13 -04: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 14:13:21 -04:00
## Backup for downgrade
2022-07-27 21:22:47 -04: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 14:13:21 -04: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-27 21:22:47 -04: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 14:13:21 -04: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-27 21:22:47 -04:00
* Replace the installed Gitea binary with the downloaded one.
2021-09-09 14:13:21 -04:00
* Start the Gitea instance.
2022-02-06 15:07:52 -05: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 14:13:21 -04:00
## Take care about customized templates
2022-07-27 21:22:47 -04: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 14:13:21 -04:00
2022-07-27 21:22:47 -04: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 14:13:21 -04:00
Remove or update the incompatible templates and Gitea web will work again.
