doc: Upgrade from an old Gitea (#16918)

* doc: Upgrade from an old Gitea

* update backup steps

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>

* update backup tips

* update table header

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: silverwind <me@silverwind.io>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: silverwind <me@silverwind.io>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: techknowlogick <matti@mdranta.net>

* Update docs/content/doc/upgrade/from-gitea.en-us.md

Co-authored-by: techknowlogick <matti@mdranta.net>

* Update from-gitea.en-us.md

* Update from-gitea.en-us.md

* Update from-gitea.en-us.md

* Update from-gitea.en-us.md

* Update from-gitea.en-us.md

* Update from-gitea.en-us.md

* Update from-gitea.en-us.md

Co-authored-by: delvh <dev.lh@web.de>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: techknowlogick <matti@mdranta.net>
Co-authored-by: techknowlogick <techknowlogick@gitea.io>

1 files changed, 86 insertions, 0 deletions

diff --git a/docs/content/doc/upgrade/from-gitea.en-us.md b/docs/content/doc/upgrade/from-gitea.en-us.md
new file mode 100644
index 0000000000..c3c46a148f
--- /dev/null
+++ b/docs/content/doc/upgrade/from-gitea.en-us.md
@@ -0,0 +1,86 @@
+---
+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:
+    parent: "upgrade"
+    name: "From Gitea"
+    weight: 10
+    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.
+Every time a Gitea instance starts up, it checks whether a database migration should be run. 
+If a database migration is required, Gitea will take some time to complete the upgrade and then serve.
+
+## Backup for downgrade
+
+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 
+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. |
+
+**Since you can not run an old Gitea with an upgraded database, 
+a backup should always be made before a database upgrade.** 
+
+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.
+* Replace the installed Gitea binary with the downloaded one. 
+* Start the Gitea instance.
+
+## Take care about customized templates
+
+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. 
+
+If the customized templates don't match Gitea version, you may experience: 
+`50x` server error, page components missing or malfunctioning, strange page layout, ... 
+Remove or update the incompatible templates and Gitea web will work again.