Admin information for the new posix storage driver

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.3.0](https://github.com/opencloud-eu/docs/releases/tag/1.3.0) - 2025-03-10
+
+### ❤️ Thanks to all contributors! ❤️
+
+@Heiko-Pohl, @ScharfViktor, @kulmann
+
+### 👷 Admin Documentation
+
+- add upgrade guide [[#154](https://github.com/opencloud-eu/docs/pull/154)]
+- Backup Tutorial [[#148](https://github.com/opencloud-eu/docs/pull/148)]
+- delete screenshot in bare metal documentation [[#149](https://github.com/opencloud-eu/docs/pull/149)]
+
+### 🐛 Bug Fixes
+
+- Fix typo on index.md [[#153](https://github.com/opencloud-eu/docs/pull/153)]
+
 ## [1.2.0](https://github.com/opencloud-eu/docs/releases/tag/1.2.0) - 2025-03-07
 
 ### ❤️ Thanks to all contributors! ❤️

docs/admin/20-getting-started/50-raspberry-pi.md

@@ -215,7 +215,7 @@ How to set up DDNS in the router:
 - Search for the DDNS settings - these are usually located under Network, Internet or Dynamic DNS.
 - Select No-IP as your provider from the list of supported DDNS services.
 - Enter your No-IP credentials (username & password).
-- Enter the hostname you previously created with No-IP (e.g. ocis-at-home.ddns.net).
+- Enter the hostname you previously created with No-IP (e.g. opencloud-at-home.ddns.net).
 - Save the settings and test the connection.
 
 The router will now automatically update your public IP address at No-IP so that your Raspberry Pi always remains accessible under the selected subdomain.

docs/admin/30-configuration/80-storage-posix.md

@@ -3,4 +3,67 @@ sidebar_position: 8
 id: storage-posix
 title: "Storage: Posix"
 draft: true
----
+---
+
+# PosixFS Storage Driver
+
+PosixFS is a storage driver that saves OpenClouds files and folders in a folder structure how the user sees that in the web interface or other clients. That is a difference compared to DecomposedFS, which stores files in a technical folder structure that has limited meaning for admins.
+
+There are two modes to distinguish:
+
+1. *non collaborative mode* where the filesystem tree in use is exclusively granted to OpenCloud
+2. *collaborative mode* where modifications of the underlying file tree are permitted by other processes than OpenCloud
+
+The *collaborative mode* is not yet available and will follow later.
+
+## Metadata
+
+To allow OpenCloud to work database-less, extra metadata is stored in the extended file attributes of each file. To mitigate size limitations for extended file attributes of file systems, metadata is moved to an extra metadata file if overall size exceeds a certain limit. In that case, only a reference to the meta data file is kept in the extended file attributes.
+
+## Access Model
+
+PosixFS in *non collaborative mode* must not be changed manually in the file system while OpenCloud is up and running. The assigned file system tree has to be exclusively granted for OpenClouds access.
+
+File- and folder permissions must be set to the same user and group that OpenCloud is running under. That is happening autmatically as long as the root directory of the tree is writeable.
+
+### External Access
+
+When OpenCloud is shut down, limited manipulation of the underlying file system tree is possible for certain administration tasks such as
+
+- adding files and folders
+- removing files and folders
+- renaming files and folders
+
+:::warning
+
+Whenever files are manipulated externally to OpenCloud, it is important to remember to
+
+- shut down OpenCloud before starting
+- do not lose the extended file attributes of individual files
+- set the file- and folder permissions correctly
+
+:::
+
+## Backup
+
+With PosixFS backup and restore is easy. The entire OpenCloud filesystem tree can be snapshotted regularly and restored as needed. It depends on the filesystem type how that has to be done in detail.
+
+## Migration
+
+PosixFS in this so called *non collaborative mode* is the default for new installations of OpenCloud. There is currently no way to migrate OpenCloud installations with DecomposedFS backend to PosixFS.
+
+If that is needed, data needs to be copied into a new installation of OpenCloud with PosixFS.
+
+# Configuration
+
+The collaborative PosixFS storage driver is part of the default OpenCloud bundle.
+
+Involved configuration settings (environment variables) to enable PosixFS are:
+
+- `STORAGE_USERS_DRIVER` needs to be set to `posix`
+- `STORAGE_USERS_ID_CACHE_STORE` needs to be set to `nats-js-kv`
+- `STORAGE_USERS_POSIX_ROOT` can be omitted for default, or set the storage root directory
+
+---
+
+

docs/admin/40-maintenance/10-upgrade.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 1
+id: update
+title: "Upgrade"
+description: "🔄 Keep your setup up to date with the latest features!"
+---
+
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+This guide provides steps to upgrade OpenCloud for both [docker](docs/admin/20-getting-started/30-docker.md) and [docker compose](docs/admin/20-getting-started/20-docker-compose.md)
+
+### 1. Stop OpenCloud
+
+Stop the currently running OpenCloud instance:
+
+<Tabs groupId="deployment">
+  <TabItem value="docker" label="docker">
+    ```Shell
+    docker stop opencloud
+    ```
+  </TabItem>
+  <TabItem value="docker-compose" label="docker compose">
+    ```Shell
+    docker compose stop
+    ``` 
+  </TabItem>
+</Tabs>
+
+---
+
+### 2. Backup Config and Data
+
+It is recommended to create a backup before proceeding with the upgrade.
+
+TODO: put backup link #103.
+
+---
+
+### 3. Pull the new Opencloud version
+
+```Shell
+docker pull opencloudeu/opencloud:{tag}
+```
+
+---
+
+### 4. Verify Configuration Changes
+
+If upgrading from an older release, check for required configuration changes:
+
+Go to inside the container:
+```Shell
+docker run --rm -it --entrypoint /bin/sh -v $HOME/opencloud/opencloud-config:/etc/opencloud opencloudeu/opencloud:{tag}
+```
+
+```Shell
+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.
+
+<img src={require("./img/init-diff.png").default} alt="init -diff" width="1920"/>
+
+---
+
+### 5. Start OpenCloud with updated image
+
+<Tabs groupId="deployment">
+  <TabItem value="docker" label="docker">
+    ```Shell
+    docker run \
+    --name opencloud \
+    --rm \
+    -it \
+    -p 9200:9200 \
+    -v $HOME/opencloud/opencloud-config:/etc/opencloud \
+    -v $HOME/opencloud/opencloud-data:/var/lib/opencloud \
+    -e OC_INSECURE=true \
+    -e PROXY_HTTP_ADDR=0.0.0.0:9200 \
+    -e OC_URL=https://localhost:9200 \
+    opencloudeu/opencloud:{tag}
+    ```
+  </TabItem>
+  <TabItem value="docker-compose" label="docker compose">
+    ```Shell
+    OC_DOCKER_IMAGE=opencloudeu/opencloud OC_DOCKER_TAG=tag docker compose up -d
+    ```
+  </TabItem>
+</Tabs>
+
+---
+
+### 6. Conclusion
+Make sure that all previously created data, users, shared files, public links exist.