From de40661897c93bc9f5ae2d3199ead4781c99bfe2 Mon Sep 17 00:00:00 2001
From: pabera <1260686+pabera@users.noreply.github.com>
Date: Fri, 22 Mar 2024 09:46:46 +0100
Subject: [PATCH] docs: Manually upgrade to the latest version (#2300)

* docs: Manually upgrade to the latest version

* Fix typo

* Fix Typos

* Solve last issue

* fix: Align with comments

* fix: indentation was off

* fix: markdown lint

* fix: one small bugfix

* fix: remove last linting issues

* fix: adding info about missing upgrade feature
---
 documentation/builders/update.md | 94 ++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/documentation/builders/update.md b/documentation/builders/update.md
index cb919492a..6a9004625 100644
--- a/documentation/builders/update.md
+++ b/documentation/builders/update.md
@@ -12,6 +12,100 @@ Restore your old files after the new installation was successful and check if ne
 $ diff shared/settings/jukebox.yaml resources/default-settings/jukebox.default.yaml
 ```
 
+## Manually upgrade to the latest version
+
+> [!CAUTION]
+> This documentation is only recommended for users running on `future3/develop` branch. For optimal system updates, it is strongly recommended to utilize the upgrade feature when transitioning to the next version (The Upgrade Feature will come in the future [#2304](https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/2304)). Manual updates may necessitate specific migration steps and, if overlooked, could result in system failure. Please use these steps with caution.
+
+If you only want to update a few recent commits, this following explanation outlines the steps to do so
+
+Typically, 4 steps need to be considered
+
+1. Backup Local Changes (Optional)
+1. Pull the latest version from Github
+1. Replace the Web App with the most recent build
+1. Optional: Update the config files
+
+### Fetch the most recent version from Github
+
+First, SSH into your Phoniebox.
+
+```bash
+cd ~/RPi-Jukebox-RFID/
+```
+
+Second, get the latest version from Github. Depending on your proficiency with Git, you can also checkout a specific branch or version.
+Be aware, in case you have made changes to the software, stash them to keep them safe.
+
+1. Backup Local Changes (Optional):
+    - Stash your local changes:
+
+        ```bash
+        git stash push -m "Backup before pull"
+        ```
+
+    - Create a Backup Branch (and potentially delete it in case it already exists):
+
+        ```bash
+        git branch -D backup-before-pull
+        git branch backup-before-pull
+        ```
+
+1. Pull Latest Changes:
+
+   ```bash
+   git pull
+   ```
+
+1. Update Web App:
+    1. Backup the current webapp build
+
+        ```bash
+        cd ~/RPi-Jukebox-RFID/src/webapp
+        rm -rf build-backup
+        mv build build-backup
+        ```
+
+    1. Go to the [Github Release page](https://github.com/MiczFlor/RPi-Jukebox-RFID/releases) find the latest `Pre-release` release (typically Alpha).
+    1. Under "Assets", find the latest Web App release called "webapp-build-latest.tar.gz" and copy the URL.
+    1. On your Phoniebox, download the file and extract the archive. Afterwards, delete the archive
+
+        ```bash
+        wget {URL}
+        tar -xzf webapp-build-latest.tar.gz
+        rm -rf webapp-build-latest.tar.gz
+        ```
+
+1. Reboot the Phoniebox:
+
+   ```bash
+   sudo reboot
+   ```
+
+1. Verify the version of your Phoniebox in the settings tab.
+
+Revert to Backup If Needed:
+
+- Checkout the backup branch:
+
+    ```bash
+    git checkout backup-before-pull
+    ```
+
+- Reapply stashed changes (if any):
+
+    ```bash
+    git stash pop
+    ```
+
+- Revert Web App:
+
+    ```bash
+    cd ~/RPi-Jukebox-RFID/src/webapp
+    rm -rf build
+    mv build-backup build
+    ```
+
 ## Migration Path from Version 2
 
 There is no update path coming from Version 2.x of the Jukebox.