From 7acc782ffe490b9a71c2e02244a83b2aa2acc363 Mon Sep 17 00:00:00 2001
From: Phan An <me@phanan.net>
Date: Wed, 17 Jul 2024 10:42:56 +0200
Subject: [PATCH] docs: improve Upgrade guide

---
 docs/guide/getting-started.md | 52 ++++++++++++++++++++++++++++++-----
 1 file changed, 45 insertions(+), 7 deletions(-)

diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index c2f753d4..7a97ac0f 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -26,7 +26,7 @@ Koel supports installing from a pre-compiled archive, which eliminates the need
 First, go to the [Releases page](https://github.com/koel/koel/releases) on GitHub, download either the `.tar.gz` or `.zip` file found under "Assets," and unzip it into the destination web root directory. From there, run the two following commands:
 
 ```bash
-php artisan koel:init --no-assets 
+php artisan koel:init --no-assets
 
 # Follow the wizard to populate necessary configurations
 
@@ -42,7 +42,7 @@ cd <KOEL_ROOT_DIR>
 git clone https://github.com/koel/koel.git .
 git checkout latest # Check out the latest version at https://github.com/koel/koel/releases
 composer install
-php artisan koel:init 
+php artisan koel:init
 
 # Follow the wizard to populate necessary configurations
 
@@ -52,9 +52,9 @@ php artisan serve
 In both cases, you should now be able to visit http://localhost:8000 in your browser and start using Koel.
 
 ::: warning Use a proper webserver
-http://localhost:8000 is only the _development_ server for Koel (or rather, Laravel). 
+http://localhost:8000 is only the _development_ server for Koel (or rather, Laravel).
 For optimal performance, you'll want to set up a production server (Apache, nginx, Caddy etc.) and point it to the `public` directory of Koel.
-Koel provides a sample configuration for nginx in `nginx.conf.example`, 
+Koel provides a sample configuration for nginx in `nginx.conf.example`,
 but the process shouldn't be any different from that of a standard PHP application.
 :::
 
@@ -65,7 +65,7 @@ Koel has an official Docker image: [koel/docker](https://github.com/koel/docker)
 ## Configuration
 
 Koel’s configuration is stored in the `.env` file at the root of the project, which is created during the installation process
-by copying the `.env.example` file and filling it with sensible values. 
+by copying the `.env.example` file and filling it with sensible values.
 You can always modify the values to suit your environment.
 
 ### Configure a Mailer
@@ -81,9 +81,47 @@ and Koel will know to remove/disable these features.
 :::danger Backup your database
 Remember to always back up your database before upgrading.
 :::
+
 Check out [Releases](https://github.com/koel/koel/releases) for upgrade guides corresponding to your Koel version and installation method.
+In general, the upgrade process involves updating the source code and dependencies, running database migrations, and occasionally, adding/updating some configuration values.
+
+### Upgrade an installation from source
+
+If you installed Koel from source, upgrading is as simple as running the following commands:
+
+```bash
+cd <KOEL_ROOT_DIR>
+git pull
+git checkout latest
+composer install
+php artisan cache:clear
+php artisan koel:init
+```
+
+### Upgrade a pre-compiled archive installation
+
+For pre-compiled archived users, download the latest archive, extract it, and replace the existing files with the new ones.
+Make sure, however, that old application code (typically `app` and `config` folders) is removed.
+
+```bash
+cd <KOEL_ROOT_DIR>
+rm -rf app config
+# assuming we're upgrading to v7.0.0
+wget -qO- https://github.com/koel/koel/releases/download/v7.0.0/koel-v7.0.0.tar.gz | tar -xvzC . --strip-components=1
+php artisan cache:clear
+php artisan koel:init --no-assets
+```
+
+### Upgrade a Docker installation
+
+For Docker users, the upgrade process is as simple as pulling the latest image and restarting the container.
+
+:::tip Always read release notes
+Again, no matter which installation method, always read the [release notes](https://github.com/koel/koel/releases) for specific guides
+as well as other important changes you might be missing.
+:::
 
 ## Downgrade
 
-Koel does not provide a built-in downgrade mechanism. 
-In the unlikely event that you need to downgrade, simply restore your database from a backup and follow the installation guide for the version you want to downgrade to. 
+Koel does not provide a built-in downgrade mechanism.
+In the unlikely event that you need to downgrade, simply restore your database from a backup and follow the installation guide for the version you want to downgrade to.