Shared storage fixes

apps/docs/content/features/backup.mdx

@@ -7,7 +7,7 @@ Zerops provides an automated, secure backup system for supported services. This
 
 ## Supported Services
 
-Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/manage#backups), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/backup).
+Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/manage#backups), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/manage#backups).
 
 ## Managing Backups in the UI
 

apps/docs/content/references/import.mdx

@@ -128,7 +128,7 @@ services:
     override: false
   # REQUIRED. Name of your other service
   - hostname: teststorage1
-    type: shared-storage
+    type: shared-storage:ha
     ...
 ```
 </DropdownItem>
@@ -322,7 +322,7 @@ services:
 
   # A second, simpler service example
   - hostname: teststorage1
-    type: shared-storage
+    type: shared-storage:ha
 ```
 
 This example includes all possible configuration options for Zerops services. Not all options are required or applicable to every service type. The example shows two services in the same YAML file: a fully configured Node.js API service and a simpler static frontend service.
@@ -696,6 +696,8 @@ services:
 
 The `mount:` parameter allows you to mount a shared storage (which should be created inside the project) to the service.
 
+The `buildFromGit` requirement exists because an import without it only creates an empty service shell with nothing deployed yet, so there is nothing to mount the storage into. With `buildFromGit`, the import also builds and deploys the repository, and the mount is applied to the deployed service. If you import a service without `buildFromGit`, deploy your application first and then connect the shared storage [in the GUI](/shared-storage/how-to/connect).
+
 ### Service Nginx Configuration
 
 The nginx configuration defines the nginx settings for the service.

apps/docs/content/shared-storage/how-to/connect.mdx

@@ -1,43 +1,74 @@
 ---
-title: Connect shared storage to a runtime service
-description: Learn how to connect shared storage to other services in Zerops.
+title: Connect & mount shared storage
+description: Learn how to connect shared storage to runtime services in Zerops and how the mount behaves.
 ---
 
-import GroupCards from '@site/src/components/GroupCards';
+This page covers how to connect an existing shared storage to runtime services, how to disconnect it, and how the mount behaves inside your containers.
 
-This page covers how to connect an existing shared storage to runtime services and how to disconnect services when needed.
+## How the mount behaves
 
-## In Zerops GUI
+Once a shared storage is connected to a runtime service, Zerops mounts it at `/mnt/<storage-hostname>` in the runtime containers. For example, `/mnt/teststorage` for a `teststorage` shared storage:
 
-### Connect a new shared storage
+<figure style={{ textAlign: 'center', margin: '1rem 0' }}>
+  <img
+    src="/img/screenshots/connect_shared_storage_2.png"
+    alt="Mounted shared storage in the file browser"
+    width="100%"
+    height="auto"
+  />
+</figure>
+
+- The content is shared among **all containers** of the connected runtime service; if you connect multiple runtime services, they all see the same content
+- Multiple storages can be mounted to a single service (e.g. `/mnt/files1`, `/mnt/files2`)
+- The mount point is owned by the `zerops` user and group (no sudo required)
+- Mounting removes any existing content of the mount directory
+- The mount is only available in runtime containers, not during build and prepare runtime phases
+- The mount process logs its standard output and error to the runtime service logs (tagged `zerops-mount-<service-hostname>`); individual file operations are not logged
 
-When creating a new shared storage service, you can directly select which runtime services it should be connected to. See [Create Shared Storage](/shared-storage/how-to/create) for details about the creation process.
+:::note
+The `df` command may show incorrect or misleading information for shared storage mounts. Refer to the Zerops GUI for accurate storage metrics.
+:::
 
-### Connect an existing shared storage
+## Connect in Zerops GUI
+
+When creating a new shared storage service, you can directly select which runtime services it should be connected to. See [Create shared storage](/shared-storage/how-to/create) for the creation process.
 
 For existing storage, go to the shared storage service detail page and select **Shared storage connections**. Toggle ON any runtime services you wish to connect to this storage.
 
 <figure style={{ textAlign: 'center', margin: '1rem 0' }}>
   <img
     src="/img/screenshots/connect_shared_storage_1.png"
-    alt="Connecting shared storage during creation"
+    alt="Connecting shared storage to runtime services"
     width="90%"
     height="auto"
   />
 </figure>
 
-## Disconnect a shared storage in Zerops GUI
+To disconnect storage, toggle OFF the desired runtime service in the same place.
 
-To disconnect storage, access the shared storage service detail page, select **Shared storage connections**, and toggle OFF the desired runtime service.
+:::note
+Connecting and disconnecting a shared storage is applied live; the runtime containers are not restarted.
+:::
 
-{/*
-## Connect using zsc
+## Mount and unmount using zsc
 
-Connect shared storage from the command line with the `zsc connectSharedStorage` command. Specify one or more storage names as parameters:
+You can also mount and unmount a shared storage from within a runtime container using the `zsc` command:
 
 ```sh
-zsc connectSharedStorage sharedstorage0
-zsc connectSharedStorage sharedDisk secondDisk
+# Mount a shared storage
+zsc shared-storage mount <storage-hostname>
+
+# Unmount a shared storage
+zsc shared-storage unmount <storage-hostname>
+
+# Wait until the storage mount is ready
+zsc shared-storage wait <storage-hostname>
 ```
 
-Run this command from within your runtime container via web terminal, SSH, or in your `zerops.yaml` file. For more details, see the [Zerops Setup Control documentation](/references/zsc).*/}
+Run these commands from your runtime container via web terminal or SSH, or as part of your `zerops.yaml` commands. For more details, see the [zsc reference](/references/zsc#shared-storage).
+
+:::caution
+The shared storage must be mounted (through the GUI connection toggle or via `zsc shared-storage mount`) before your application can access the `/mnt/<storage-hostname>` directory.
+
+Before stopping or deleting a shared storage service, you must first disconnect (unmount) it from all runtime services.
+:::

apps/docs/content/shared-storage/how-to/create.mdx

@@ -6,11 +6,9 @@ description: Learn how to create shared storage which you can use with your othe
 import GroupCards from '@site/src/components/GroupCards';
 import Video from '@site/src/components/Video';
 
-Shared Storage provides persistent file storage that can be mounted as a POSIX-compatible filesystem to your runtime services. Built on [SeaweedFS ↗](https://github.com/seaweedfs/seaweedfs), it enables reliable data persistence and sharing across services in your infrastructure.
-
 ## Create Using Zerops GUI
 
-First, set up a project in Zerops GUI and add a runtime service. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Shared Storage service:
+Go to your project dashboard and choose **Add new service** in the left menu in the **Services** block. Then add a new Shared Storage service:
 
 <Video
   src="/vids/services/shared-storage.webm"
@@ -19,74 +17,84 @@ First, set up a project in Zerops GUI and add a runtime service. Then go to the
 
 ### Set a Hostname
 
-Enter a unique service identifier like "storage", "files" etc. Duplicate services with the same name in the same project are forbidden.
-
-#### Hostname Limitations:
+Enter a unique service identifier like "storage", "files" etc.
 
 - Maximum 25 characters
 - Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+- Must be unique within the project
 
 :::note
 The hostname is fixed after the service is created. It can't be changed later.
 :::
 
 ### Connect to Services
 
-Select one or more project's runtime services in the Share with Services block:
+Select one or more of the project's runtime services in the **Share with Services** block:
 
 <figure style={{ textAlign: 'center', margin: '1rem 0' }}>
   <img
     src="/img/screenshots/connect_shared_storage.png"
-    alt="image"
+    alt="Selecting runtime services to share the storage with"
     width="100%"
     height="auto"
   />
 </figure>
 
-The new Shared Storage will be connected to the selected runtimes.
-
-:::note
-Runtime services can be connected and disconnected at any time even after the shared storage is created.
-:::
+Runtime services can be [connected and disconnected](/shared-storage/how-to/connect) at any time, even after the shared storage is created.
 
 ### Choose Deployment Mode
 
-Choose between **Highly Available** (recommended for production) or **Single Container** (suitable for development) deployment.
+Choose between **Highly Available** (recommended for production) and **Single Container** (suitable for development). See the [mode comparison](/shared-storage/overview#deployment-modes) and [technical details](/shared-storage/tech-details#deployment-modes).
 
 :::warning
-The Shared Storage deployment mode is fixed after the service is created. It can't be changed later.
-
-See [Technical Details](/shared-storage/tech-details#deployment-modes) for more information about deployment modes.
+The deployment mode is fixed after the service is created. It can't be changed later.
 :::
 
 ### Set Auto Scaling Configuration
 
-Configure vertical auto scaling parameters to control resource allocation and costs.
+Configure vertical auto scaling parameters to control resource allocation and costs:
 
 <figure style={{ textAlign: 'center', margin: '1rem 0' }}>
   <img
     src="/img/screenshots/shared_storage_autoscaling.png"
-    alt="image"
+    alt="Shared storage autoscaling configuration"
     width="100%"
     height="auto"
   />
 </figure>
 
 :::note
-For detailed information about auto scaling capabilities and recommendations, see [Technical Details](/shared-storage/tech-details#auto-scaling-configuration).
+Raising the disk limits does not raise the usable data capacity, which is capped at 60GB. See [Storage Capacity](/shared-storage/tech-details#storage-capacity) and [Auto Scaling Configuration](/shared-storage/tech-details#auto-scaling-configuration).
+:::
+
+## Create Using Import YAML
+
+The deployment mode is part of the service type:
+
+```yaml title="zerops-import.yaml"
+services:
+  - # Shared storage service in highly available mode
+    hostname: teststorage
+    type: shared-storage:ha
+```
+
+Use `shared-storage:single` for the single container mode.
+
+:::note
+You can also pin the underlying engine version directly with `seaweedfs:ha@3` or `seaweedfs:single@3`.
 :::
 
-## Create Using zCLI
+Import the file with the [zCLI](/references/cli):
 
-zCLI is the Zerops command-line tool. To create a new Shared Storage service via the command-line, follow these steps:
+```sh
+zcli project service-import zerops-import.yaml
+```
 
-1. [Install & setup zCLI](/references/cli)
-2. Create a project description file
-3. Create a project with a runtime and a Shared Storage service
+To mount the storage into a runtime service in the same import, add the `mount:` parameter to the runtime service. See the [import reference](/references/import#service-mount-shared-storage) for details and requirements.
 
-### Choose Your Runtime
+### Runtime-Specific Guides
 
-<GroupCards heading="Read about how to create a project description file and create a runtime service with a Shared storage." items={languages} />
+<GroupCards heading="Create a runtime service with a Shared storage via import YAML." items={languages} />
 
 export const languages = [
     { name: "Node.js", link: "/nodejs/how-to/shared-storage#create-nodejs-service-with-a-shared-storage-using-zcli" },
@@ -95,4 +103,4 @@ export const languages = [
     { name: "Go", link: "/go/how-to/shared-storage#create-go-service-with-a-shared-storage-using-zcli" },
     { name: ".NET", link: "/dotnet/how-to/shared-storage#create-dotnet-service-with-a-shared-storage-using-zcli" },
     { name: "Rust", link: "/rust/how-to/shared-storage#create-rust-service-with-a-shared-storage-using-zcli" }
-]
+]

apps/docs/content/shared-storage/how-to/manage.mdx

@@ -1,26 +1,28 @@
 ---
-title: Manage and Access Shared Storage
-description: Learn how to manage, monitor, and troubleshoot your Shared Storage in Zerops.
+title: Manage and back up Shared Storage
+description: Learn how to manage, monitor, back up, and restore your Shared Storage in Zerops.
 ---
 
-Zerops Shared Storage provides several web interfaces to manage, monitor, and troubleshoot your storage. These interfaces are accessible through the [Zerops VPN](/references/networking/vpn) and offer different capabilities for managing your data and monitoring system performance.
+Zerops Shared Storage provides several web interfaces to manage, monitor, and troubleshoot your storage, and automated encrypted backups of your data.
 
-## Access Web Interfaces
+## Web interfaces
+
+The web interfaces are accessible through the [Zerops VPN](/references/networking/vpn).
 
 ### Filer UI
 
 * `http://<storage-service-hostname>.zerops:8888`
 
-The Filer UI provides a web-based interface for managing files and directories in your Shared Storage:
+A web-based interface for managing files and directories:
 - Browse the directory structure and create new directories
-- Upload new files (up to 64MB) and download existing files
+- Upload new files (up to 64MB per file) and download existing files
 - Rename and delete files and directories
 
 ### Master UI
-* `http://node-stable-1.db.<storage-service-hostname>.zerops:9333`
 
-The Master UI provides system status and monitoring information:
+* `http://node-stable-1.db.<storage-service-hostname>.zerops:9333`
 
+System status and monitoring information:
 - View cluster topology
 - Monitor volume servers
 - Check system status and health
@@ -30,8 +32,7 @@ The Master UI provides system status and monitoring information:
 
 * `http://node-stable-<node-number>.db.<storage-service-hostname>.zerops:8080/ui/index.html`
 
-The Volume UI allows you to monitor individual storage volumes:
-
+Monitoring of individual storage volumes:
 - View volume status
 - Check disk usage
 - Monitor I/O operations
@@ -41,11 +42,42 @@ The Volume UI allows you to monitor individual storage volumes:
 
 Several options are available to help you monitor your Shared Storage:
 
-### Runtime Service Logs
-* Navigate to your runtime service detail page → **Runtime Logs** section → filter using the tag `zerops-mount-<service-hostname>`
+- **Runtime service logs**: navigate to your runtime service detail page, open the **Runtime Logs** section, and filter using the tag `zerops-mount-<service-hostname>` (standard output and error of the mount process)
+- **Shared Storage logs**: access from the Shared Storage service detail page, **Runtime Logs** tab
+- **System and volume status**: monitor replication status, disk usage, and performance metrics through the Master UI and Volume UI
+
+## Backups
+
+Zerops provides automated data backup for Shared Storage services with full encryption.
+
+For general backup information including configuration, scheduling, retention, tagging, quotas, and CLI tools, see the [Zerops Backups](/features/backup) documentation.
+
+### Backup format
+
+Shared Storage backups are created using tar archival:
+
+- **Format**: `.tar.gz` (archive of the directory contents)
+- **Content**: the entire shared volume (`/mnt/<storage-hostname>`)
+- **Storage**: encrypted and stored in isolated object storage
+
+### Restoring backups
+
+To restore a Shared Storage backup:
+
+1. Download the backup file (`.tar.gz`) from the Zerops UI.
+2. Transfer the archive into a runtime service that has the shared storage [connected](/shared-storage/how-to/connect), for example over the [Zerops VPN](/references/networking/vpn).
+3. Extract the archive into the mount directory from within the runtime container:
+
+```sh
+tar -xzf backup.tar.gz -C /mnt/<storage-hostname>
+```
+
+:::note
+Do not restore by uploading files through the Filer UI. Uploads there are limited to 64MB per file, so extracting the archive directly into the mounted directory is the reliable path.
+:::
 
-### Shared Storage Logs
-* Access from the Shared Storage service detail page → **Runtime Logs** tab → browse or search for relevant information
+### Best practices
 
-### System and Volume Status
-* Monitor replication status, disk usage, and performance metrics through the Master UI and Volume UI
+- Regularly clean up unnecessary files from your Shared Storage to reduce backup size
+- Create manual backups with protected tags before major file operations or migrations
+- Test your restore process periodically to ensure data integrity