improvement standard upgrade guide

docs/admin/maintenance/upgrade/upgrade-7.x.x.md

@@ -98,12 +98,12 @@ docker stop opencloud
 
 Pull the OpenCloud 7.x.x image.
 
+Replace `7.x.x` with the exact image tag for the version you want to install. Available tags are listed on [Docker Hub](https://hub.docker.com/u/opencloudeu).
+
 ```bash
 docker pull opencloudeu/opencloud:7.x.x
 ```
 
-Replace `7.x.x` with the exact OpenCloud version you want to upgrade to.
-
 ## Apply the Configuration Migration
 
 OpenCloud 7.x.x includes a breaking configuration change that must be applied before starting the upgraded instance.

docs/admin/maintenance/upgrade/upgrade.md

@@ -31,46 +31,221 @@ Stop the currently running OpenCloud instance:
   </TabItem>
 </Tabs>
 
-## Backup Config and Data
+## Back Up Configuration and Data
 
-It is recommended to create a [backup](../backup) before proceeding with the upgrade.
+<Tabs>
+  <TabItem value="bind-mounts" label="Using Bind Mounts">
 
-## Pull the latest OpenCloud Compose
+If your configuration and data are stored in directories on the host, create a copy of these directories.
 
-If you are using Docker Compose with the `opencloud-compose` repository, update your local checkout before pulling the new container image.
+Example:
 
-Skip this step if you run OpenCloud with plain Docker (`docker run`):
+```bash
+cp -a /mnt/opencloud/config /mnt/opencloud/config-backup
+cp -a /mnt/opencloud/data /mnt/opencloud/data-backup
+```
+
+Replace the paths with the directories used by your deployment.
+
+  </TabItem>
+
+  <TabItem value="named-volumes" label="Using Named Volumes">
+
+Create a backup directory and copy the configuration and data from the OpenCloud container.
+
+```bash
+mkdir -p ~/opencloud-backups
+docker cp opencloud-compose-opencloud-1:/etc/opencloud ~/opencloud-backups/config-backup
+docker cp opencloud-compose-opencloud-1:/var/lib/opencloud ~/opencloud-backups/data-backup
+```
+
+Replace `opencloud-compose-opencloud-1` with the name of your OpenCloud container if it differs.
+
+  </TabItem>
+</Tabs>
+
+## Update the `opencloud-compose` Checkout
+
+If you use the `opencloud-compose` repository, update your local copy of the repository.
 
 ```bash
 cd /opencloud-compose
 git pull
 ```
 
-## Pull the new Opencloud version
+Skip this step if you run OpenCloud with plain Docker.
+
+## Stop OpenCloud
+
+Stop the currently running OpenCloud instance.
+
+<Tabs>
+  <TabItem value="docker-compose" label="Docker Compose">
 
 ```bash
-docker pull opencloudeu/opencloud-rolling:{tag} # or opencloudeu/opencloud:{tag} depending on the version you're using
+docker compose stop
+```
+
+  </TabItem>
+
+  <TabItem value="docker" label="Docker">
+
+```bash
+docker stop opencloud
+```
+
+  </TabItem>
+</Tabs>
+
+## Pull the new OpenCloud image
+
+Pull the image that matches the release channel you use:
+
+- `opencloudeu/opencloud-rolling:{tag}` for rolling releases
+- `opencloudeu/opencloud:{tag}` for stable releases
+
+Replace `{tag}` with the image tag for the version you want to install. Available tags are listed on [Docker Hub](https://hub.docker.com/u/opencloudeu).
+
+```bash
+docker pull opencloudeu/opencloud-rolling:{tag}
 ```
 
 ## Verify Configuration Changes
 
 If upgrading from an older release, check for required configuration changes:
 
-Go inside the container:
+### Open a Temporary OpenCloud Container
+
+Open a shell in a temporary OpenCloud container and mount your OpenCloud configuration directory or configuration volume to `/etc/opencloud`.
+
+<Tabs>
+  <TabItem value="named-volumes" label="Using Named Volumes">
+
+```bash
+docker run --rm -it --entrypoint /bin/sh -v "<opencloud-config-volume>:/etc/opencloud" opencloudeu/opencloud (or opencloud-rolling):"version-tag"
+```
+
+Replace `<opencloud-config-volume>` with the Docker volume or bind mount that contains your OpenCloud configuration.
+
+  </TabItem>
+
+  <TabItem value="bind-mounts" label="Using Bind Mounts">
 
 ```bash
-docker run --rm -it --entrypoint /bin/sh -v /YOUR/OC_CONFIG/PATH:/etc/opencloud opencloudeu/opencloud-rolling:{tag}
-# or opencloudeu/opencloud:{tag} depending on the version you're using
+docker run --rm -it --entrypoint /bin/sh -v "<path-to-your-config-directory>:/etc/opencloud" opencloudeu/opencloud (or opencloud-rolling):"version-tag"
 ```
 
+Replace `<path-to-your-config-directory>` with the host directory that contains your `opencloud.yaml`.
+
+  </TabItem>
+</Tabs>
+
+### Generate the Configuration Diff
+
+Inside the temporary container, run:
+
 ```bash
 opencloud init --diff
 ```
 
-If you see `no changes, your config is up to date`, no further action is needed. Otherwise, update your `opencloud.yaml` file accordingly and start OpenCloud.
+If you see `no changes, your config is up to date`, no further action is needed.
 
 <img src={require("../img/init-diff.png").default} alt="init -diff" width="1920"/>
 
+In that case, [exit the temporary container](#exit-the-temporary-container) and start OpenCloud.
+
+Otherwise, update your `opencloud.yaml` file accordingly and [apply the patch](#apply-the-configuration-patch).
+
+Example output:
+
+```diff
+diff -u /etc/opencloud/opencloud.yaml /etc/opencloud/opencloud.yaml.tmp
+--- /etc/opencloud/opencloud.yaml
++++ /etc/opencloud/opencloud.yaml.tmp
+@@ -90,6 +90,9 @@
+ sharing:
+   events:
+     tls_insecure: false
++service_account:
++  service_account_id: 00000000-0000-0000-0000-000000000000
++  service_account_secret: example-service-account-secret
+ storage_users:
+   events:
+     tls_insecure: false
+
+diff written to /etc/opencloud/opencloud.config.patch
+```
+
+The command creates the following patch file:
+
+```bash
+/etc/opencloud/opencloud.config.patch
+```
+
+### Apply the Configuration Patch
+
+Change to the configuration directory:
+
+```bash
+cd /etc/opencloud
+```
+
+Verify that the patch file was created:
+
+```bash
+ls
+```
+
+Example output:
+
+```bash
+banned-password-list.txt
+csp.yaml
+opencloud.config.patch
+opencloud.yaml
+opencloud.yaml.2026-05-19-15-45-44.backup
+```
+
+Test the patch before applying it:
+
+```bash
+patch --dry-run opencloud.yaml < opencloud.config.patch
+```
+
+Expected output:
+
+```bash
+checking file opencloud.yaml
+```
+
+Apply the patch:
+
+```bash
+patch opencloud.yaml < opencloud.config.patch
+```
+
+Expected output:
+
+```bash
+patching file opencloud.yaml
+```
+
+Verify that the following configuration entries exist in `opencloud.yaml`:
+
+```yaml
+service_account:
+  service_account_id: 00000000-0000-0000-0000-000000000000
+  service_account_secret: example-service-account-secret
+```
+
+### Exit the Temporary Container
+
+Exit the temporary container after applying the configuration patch.
+
+```bash
+exit
+```
+
 ## Start OpenCloud with updated image
 
 <Tabs groupId="deployment">

package.json

@@ -59,5 +59,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "packageManager": "pnpm@9.15.4+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
+  "packageManager": "pnpm@11.6.0"
 }

pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  core-js: true
+  esbuild: true