From 4f449ef8cb463b32d722d8d9d6bfe26a57c708f1 Mon Sep 17 00:00:00 2001 From: Heiko Pohl Date: Mon, 21 Jul 2025 10:38:32 +0200 Subject: [PATCH 1/2] reworking amin maintenance docs --- docs/admin/maintenance/backup.md | 44 +++++------- docs/admin/maintenance/dataexport.md | 5 +- docs/admin/maintenance/migrate.md | 71 ++++++++----------- docs/admin/maintenance/uninstall.md | 19 ++--- .../maintenance/upgrade/release-notes.md | 15 ++-- docs/admin/maintenance/upgrade/upgrade.md | 29 +++----- 6 files changed, 79 insertions(+), 104 deletions(-) diff --git a/docs/admin/maintenance/backup.md b/docs/admin/maintenance/backup.md index 2dae4602..850a7458 100644 --- a/docs/admin/maintenance/backup.md +++ b/docs/admin/maintenance/backup.md @@ -1,16 +1,18 @@ --- sidebar_position: 2 id: backup -title: 'Backup' +title: Backup +description: Backup +draft: false --- -## Regular backups are essential to ensure that your OpenCloud instance can be restored in case of issues +# Backup ---- +Regular backups are essential to ensure that your OpenCloud instance can be restored in case of issues -### General considerations +## General considerations -#### OpenCloud supports two different storage setups +### OpenCloud supports two different storage setups - Pure POSIX Setup: All data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem. @@ -18,13 +20,11 @@ title: 'Backup' To determine which filesystems are supported, see: Filesystems and Shared Storage ---- - -### Backup strategies +## Backup strategies -#### To create a consistent backup, the OpenCloud instance must be stopped before starting the backup process. After the backup is complete, the instance can be restarted +### To create a consistent backup, the OpenCloud instance must be stopped before starting the backup process. After the backup is complete, the instance can be restarted -**There are two recommended approaches:** +There are two recommended approaches: - Snapshot-based backup (recommended) - If your storage system supports snapshots, creating a backup only takes a few seconds @@ -37,11 +37,9 @@ To determine which filesystems are supported, see: Filesystems and Shared Storag - For more details on data locations, refer to the Default Paths documentation ---- - -### Required backup components +## Required backup components -#### A complete backup must include +### A complete backup must include - Configuration data @@ -61,11 +59,9 @@ To determine which filesystems are supported, see: Filesystems and Shared Storag - This ensures compatibility when restoring and prevents issues caused by software version mismatches ---- +## Pure POSIX setup -### Pure POSIX setup - -#### If all data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem +### If all data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem - Stop the OpenCloud instance @@ -77,11 +73,9 @@ To determine which filesystems are supported, see: Filesystems and Shared Storag - Restart the OpenCloud instance after the backup is complete ---- - -### Distributed setup +## Distributed setup -#### If blobs are stored on S3, while configuration and metadata remain on a POSIX-compliant filesystem +### If blobs are stored on S3, while configuration and metadata remain on a POSIX-compliant filesystem - Stop the OpenCloud instance @@ -91,6 +85,6 @@ To determine which filesystems are supported, see: Filesystems and Shared Storag - Restart the OpenCloud instance after the backup is complete ---- - -#### With these backup strategies, you can ensure that your OpenCloud instance remains secure and restorable in case of issues +:::note +With these backup strategies, you can ensure that your OpenCloud instance remains secure and restorable in case of issues +::: diff --git a/docs/admin/maintenance/dataexport.md b/docs/admin/maintenance/dataexport.md index 5d81df01..21081de5 100644 --- a/docs/admin/maintenance/dataexport.md +++ b/docs/admin/maintenance/dataexport.md @@ -1,8 +1,9 @@ --- sidebar_position: 5 id: dataexport -title: 'Data Export' -description: 'Information about data export.' +title: Data Export +description: Information about data export. +draft: false --- # Data Export diff --git a/docs/admin/maintenance/migrate.md b/docs/admin/maintenance/migrate.md index 64dfe175..97c44cdb 100644 --- a/docs/admin/maintenance/migrate.md +++ b/docs/admin/maintenance/migrate.md @@ -1,23 +1,26 @@ --- sidebar_position: 3 id: migrate -title: 'Migrate' -description: 'Guide to migrating data using rclone.' +title: Migrate +description: Guide to migrating data using rclone. +draft: false --- import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -## ๐Ÿš€ Migrate Personal Space Data to OpenCloud Using rclone +# Migrate + +Migrate Personal Space Data to OpenCloud Using rclone This guide will help you migrate personal space data from `NextCloud` and `oCIS` to `OpenCloud` using `rclone`. Follow these steps carefully to ensure a smooth migration! -### 1. Generate users token using CLI or API +## Generate users token using CLI or API -### Run OpenCloud with the following configuration +## Run OpenCloud with the following configuration Modify `.env` file: @@ -45,9 +48,7 @@ Generate an authentication token for a user (e.g., `alan`) with expiration (`h`, opencloud auth-app create --user-name=alan --expiration=72h ``` ---- - -### Generate user token using API +## Generate user token using API Requires additional configuration! Start the server with: @@ -79,7 +80,7 @@ Enable `auth-app` service: PROXY_ENABLE_APP_AUTH="true" ``` -### Generate user token using CLI +## Generate user token using CLI Access the oCIS container: @@ -93,9 +94,7 @@ Generate an authentication token for a user (e.g., `einstein`) with expiration ( ocis auth-app create --user-name=einstein --expiration=72h ``` ---- - -### Generate user token using API +## Generate user token using API Requires additional configuration! Start the server with: @@ -122,23 +121,17 @@ Create a new App Password ---- - -### 2. Install rclone - -Download and install rclone by following the official guide: ๐Ÿ”—[**rclone.org/install**](https://rclone.org/install/) +## Install rclone ---- +Download and install rclone by following the official guide: [rclone.org/install](https://rclone.org/install/) -### 3. Encrypt Authentication Tokens ๐Ÿ”’ +## Encrypt Authentication Tokens ```bash rclone obscure ``` ---- - -### 4. Create the rclone Configuration ๐Ÿ› ๏ธ +## Create the rclone Configuration Edit the rclone configuration file: @@ -146,7 +139,7 @@ Edit the rclone configuration file: nano ~/.config/rclone/rclone.conf ``` -๐Ÿ“Œ Example Configuration: +- Example Configuration ```bash [opencloud-admin] @@ -205,9 +198,7 @@ description = nc-bob ``` ---- - -### 5. Copy Data to OpenCloud +## Copy Data to OpenCloud Use `rclone copy` to transfer data from `oCIS` and `Nextcloud` to `OpenCloud`: @@ -218,25 +209,21 @@ rclone copy nc-bob:/ opencloud-alan:/ --no-check-certificate -P # Copy Nextclou ``` ---- - -### 6. Migration Results and Limitations - -๐ŸŽ‰ Congratulations! You have successfully migrated personal space data to OpenCloud! ๐Ÿš€ - -โœ… Successfully Migrated: +## Migration Results and Limitations -- Personal space files +Congratulations! You have successfully migrated personal space data to OpenCloud! -โŒ Not Migrated: +- Successfully Migrated + - Personal space files -- Shared files -- Public links -- Project spaces -- Trash-bin contents -- File versions -- Metadata +- Not Migrated + - Shared files + - Public links + - Project spaces + - Trash-bin contents + - File versions + - Metadata -### 7. Security Step: Delete Tokens +## Security Step: Delete Tokens Once the migration is complete, please delete tokens to prevent unauthorized access! diff --git a/docs/admin/maintenance/uninstall.md b/docs/admin/maintenance/uninstall.md index bb665ee4..d7750380 100644 --- a/docs/admin/maintenance/uninstall.md +++ b/docs/admin/maintenance/uninstall.md @@ -1,17 +1,18 @@ --- sidebar_position: 4 id: uninstall -title: 'Uninstall' -description: 'Guide to uninstall OpenCloud.' +title: Uninstall +description: Guide to uninstall OpenCloud. +draft: false --- # Uninstall OpenCloud with Docker Compose -> โš ๏ธ **Warning:** This guide will completely remove all OpenCloud data. Make sure to back up any important files before proceeding. +:::warning +This guide will completely remove all OpenCloud data. Make sure to back up any important files before proceeding. +::: ---- - -## Step 1: Stop and Remove Docker Containers +## Stop and Remove Docker Containers Navigate to your `opencloud-compose` directory (where your `docker-compose.yml` file is located), then run: @@ -25,7 +26,7 @@ To also remove unnamed volumes and orphan containers: docker compose down --volumes --remove-orphans ``` -## Step 2: Remove Docker Volumes +## Remove Docker Volumes To check your existing volumes: @@ -51,7 +52,7 @@ Or to clean up all unused volumes (be careful!): docker volume prune ``` -## Step 3: Delete Mounted Directories (if used) +## Delete Mounted Directories (if used) If your .env referenced local folders such as /mnt/opencloud/data, you should delete those manually: @@ -62,7 +63,7 @@ sudo rm -rf /mnt/opencloud/config Adjust the paths to match your setup. -## Step 4: Remove the Compose Project Folder (Optional) +## Remove the Compose Project Folder (Optional) If you want to delete the entire project directory: diff --git a/docs/admin/maintenance/upgrade/release-notes.md b/docs/admin/maintenance/upgrade/release-notes.md index c9b21bfd..6440e596 100644 --- a/docs/admin/maintenance/upgrade/release-notes.md +++ b/docs/admin/maintenance/upgrade/release-notes.md @@ -1,27 +1,24 @@ --- sidebar_position: 3 id: release-notes -title: 'Release Notes' +title: Release Notes +description: Release Notes draft: false --- -# ๐Ÿ“ฆ Release Notes: Migration from v2.x.x to v3.0.0 +# Release Notes: Migration from v2.x.x to v3.0.0 - Version: 3.0.0 - Type: Major Release (Breaking Changes in the GraphAPI) - [Details ยท Download](https://github.com/opencloud-eu/opencloud/releases/tag/v3.0.0) ---- - ## Who Is Affected? -This release introduces a **breaking change in the GraphAPI**. -If you are using OpenCloud only through official clients (Web, Desktop, or Mobile), **no migration is needed**. +This release introduces a breaking change in the GraphAPI. +If you are using OpenCloud only through official clients (Web, Desktop, or Mobile), no migration is needed. If you're using any other software that utilizes the GraphAPI, that software might need to be adjusted to follow the new behavior of the GraphAPI. ---- - ## Key Changes The following endpoints of the GraphAPI were changed in a way that is not backwards compatible with the previous releases: @@ -33,4 +30,6 @@ GET /v1beta1/drives/ GET /v1beta1/me/drives/ ``` +:::note Due to performance optimizations, these endpoints no longer automatically expand all permissions on the drives root items. If needed, the permissions can be explicitly requested via the appropriate $expand query option. +::: diff --git a/docs/admin/maintenance/upgrade/upgrade.md b/docs/admin/maintenance/upgrade/upgrade.md index 5f37b0f5..6743c31a 100644 --- a/docs/admin/maintenance/upgrade/upgrade.md +++ b/docs/admin/maintenance/upgrade/upgrade.md @@ -1,16 +1,19 @@ --- sidebar_position: 1 id: update -title: 'Upgrade' -description: '๐Ÿ”„ Keep your setup up to date with the latest features!' +title: Upgrade +description: Keep your setup up to date with the latest features! +draft: false --- +# Upgrade + import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' This guide provides steps to upgrade OpenCloud for both [docker](docs/admin/getting-started/container/docker.md) and [docker compose](docs/admin/getting-started/container/docker-compose/docker-compose-base.md) -### 1. Stop OpenCloud +## Stop OpenCloud Stop the currently running OpenCloud instance: @@ -27,23 +30,17 @@ Stop the currently running OpenCloud instance: ---- - -### 2. Backup Config and Data +## Backup Config and Data It is recommended to create a [backup](../backup.md) before proceeding with the upgrade. ---- - -### 3. Pull the new Opencloud version +## Pull the new Opencloud version ```bash docker pull opencloudeu/opencloud:{tag} ``` ---- - -### 4. Verify Configuration Changes +## Verify Configuration Changes If upgrading from an older release, check for required configuration changes: @@ -61,9 +58,7 @@ If you see `no changes, your config is up to date`, no further action is needed. init -diff ---- - -### 5. Start OpenCloud with updated image +## Start OpenCloud with updated image @@ -88,8 +83,6 @@ If you see `no changes, your config is up to date`, no further action is needed. ---- - -### 6. Conclusion +## Conclusion Make sure that all previously created data, users, shared files, public links exist. From 606c88d68450956f968386127b5f0a77282c8df7 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 21 Jul 2025 14:17:38 +0200 Subject: [PATCH 2/2] adjust backup --- docs/admin/maintenance/backup.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/admin/maintenance/backup.md b/docs/admin/maintenance/backup.md index 850a7458..71bfa6ca 100644 --- a/docs/admin/maintenance/backup.md +++ b/docs/admin/maintenance/backup.md @@ -12,7 +12,9 @@ Regular backups are essential to ensure that your OpenCloud instance can be rest ## General considerations -### OpenCloud supports two different storage setups +### Storage Options + +OpenCloud supports two different storage setups: - Pure POSIX Setup: All data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem. @@ -22,7 +24,9 @@ To determine which filesystems are supported, see: Filesystems and Shared Storag ## Backup strategies -### To create a consistent backup, the OpenCloud instance must be stopped before starting the backup process. After the backup is complete, the instance can be restarted +### Consistent Backup Requirement + +To create a consistent backup, the OpenCloud instance must be stopped before starting the backup process. After the backup is complete, the instance can be restarted There are two recommended approaches: @@ -31,16 +35,13 @@ There are two recommended approaches: - Snapshots should be copied to secondary storage or used by backup software for additional security --Backup software approach +- Backup software approach - - If snapshots are not available, you can use any backup software of your choice - - - For more details on data locations, refer to the Default Paths documentation +- If snapshots are not available, you can use any backup software of your choice +- For more details on data locations, refer to the Default Paths documentation ## Required backup components -### A complete backup must include - - Configuration data - System data (shares the root path with metadata if not defined separately) @@ -61,7 +62,7 @@ There are two recommended approaches: ## Pure POSIX setup -### If all data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem +If all data (configuration, blobs, and metadata) is stored on a POSIX-compliant filesystem - Stop the OpenCloud instance @@ -75,7 +76,7 @@ There are two recommended approaches: ## Distributed setup -### If blobs are stored on S3, while configuration and metadata remain on a POSIX-compliant filesystem +If blobs are stored on S3, while configuration and metadata remain on a POSIX-compliant filesystem - Stop the OpenCloud instance