From 3e3b73f50e4ee8865a23adad1ac4561c67a31043 Mon Sep 17 00:00:00 2001
From: Nathan Povo <17831160+nathanpovo@users.noreply.github.com>
Date: Mon, 25 Mar 2024 18:54:48 +0100
Subject: [PATCH] docs: Add info on upgrading package on steamdeck (#1271)

* Add info on upgrading package on steamdeck

* Improve documentation
---
 docs/posts/steamdeck_guide.md | 46 +++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/posts/steamdeck_guide.md b/docs/posts/steamdeck_guide.md
index 0d0e79e406..87441eedf2 100644
--- a/docs/posts/steamdeck_guide.md
+++ b/docs/posts/steamdeck_guide.md
@@ -1,5 +1,51 @@
 Latest SteamOS (version 3.5 and later) already pre-installed `distrobox` and `podman`.
 
+Before using `distrobox` on SteamOS, it may be necessary to upgrade to the latest version since the version provided by
+SteamOS may be outdated. You can verify the currently installed version by running the command `distrobox version`. For
+instance, on SteamOS 3.5, version 1.4.2.1-3 of `distrobox` is installed.
+
+To upgrade `distrobox` on SteamOS, you have two options:
+
+### Option 1: Install `distrobox` in `$HOME`
+
+By installing `distrobox` in your `$HOME` directory, you can ensure that you have control over the version you're using,
+independent of SteamOS updates. This method prevents your modifications from being reverted when SteamOS is updated.
+
+Note that it's essential to add this new version of `distrobox` to your PATH to ensure it's utilized over the
+SteamOS-provided version.
+
+To install `distrobox` in the `$HOME` directory, run the following command:
+
+```sh
+curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix $HOME
+```
+
+For more detailed installation instructions, refer to the documentation
+[here](https://github.com/89luca89/distrobox/blob/main/docs/README.md#alternative-methods).
+
+To upgrade the version of `distrobox`, follow the instructions provided in the documentation link above.
+
+### Option 2: Overwrite the provided `distrobox` installation in SteamOS
+
+An alternative approach is to upgrade the version of `distrobox` provided by SteamOS. While this simplifies management
+as you don't need to modify your PATH and you wouldn't have 2 versions of `distrobox` installed, it comes with the
+downside that your upgrades will be overwritten when SteamOS is updated.
+
+To upgrade the `distrobox` version provided by SteamOS, execute the following commands:
+
+```sh
+sudo steamos-readonly disable
+curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sudo sh -s -- --prefix /usr
+sudo steamos-readonly enable
+```
+
+Please note that disabling the read-only state is necessary to perform this upgrade. You can find more information about
+this requirement [here](https://help.steampowered.com/en/faqs/view/671A-4453-E8D2-323C).
+
+Once `distrobox` is upgraded, you can use it as normal.
+
+---
+
 To run GUI application, add following line to `~/.distroboxrc`.
 
 ```sh