Volumes documentation

pages/edge/configuration.mdx

@@ -130,6 +130,28 @@ redirect:
 
 ### `capabilities`
 
+### Volumes
+
+Configure persistent volume storage for your apps.
+
+*Note*: currently volumes are limited to a specific region, and provide
+read-write-many semantics.
+This means databases and other more complex use-cases will not work well just yet.
+
+```yaml filename="app.yaml" copy
+volumes:
+  # A name for your volume.
+  # Must be unique for the given app.
+  - name: data
+    # Where to moint the volume into the filesystem.
+    # You can specify multiple mounts with optional subpaths.
+    mounts:
+      # Mount the volume to `/data`.
+      - mount_path: /data
+ # Optional: the subdirectory of the volume to mount.
+ # subpath: /subpath
+```
+
 #### `instaboot`
 
 Enable fast application startup with startup snapshots.

pages/edge/learn/_meta.json

@@ -4,5 +4,6 @@
   "deployment-modes": "Deployment Modes",
   "remote-sessions": "Remote Sessions",
   "connecting-domains-to-edge": "Connecting Custom Domains to Edge",
-  "secrets": "Secrets"
+  "secrets": "Secrets",
+  "volumes": "Volumes"
 }

pages/edge/learn/volumes.mdx

@@ -0,0 +1,129 @@
+import { Callout } from "nextra-theme-docs";
+
+# Volumes
+
+Volumes provide persistent disk storage for applications.
+
+They also support remote access with any S3 compatible client.
+
+
+<Callout type="warning">
+In the current initial implementation, volumes are restricted to a single
+[Edge region](/edge/learn/regions).
+
+Volumes also at the moment only provide *read-write-many* semantics.
+Due the automatic auto-scaling for apps, this means that volumes are not currently
+well-suited for databases or other more complex use cases that require a single writer.
+
+Keep in mind that volumes can be accessed concurrently, and even from different
+nodes.
+
+These restrictions (including the single-region restriction) will be lifted
+in the future.
+</Callout>
+
+## Configuring Volumes
+
+* Every app may have multiple volumes.
+* Each volume has a name, which must be unique for the application.
+* Volumes can be mounted at a chosen path.
+* Each volume can be mounted multiple times.
+
+Simply extend your [app configuration](/edge/configuration) with a `volumes`
+section:
+
+```yaml filename="app.yaml" copy
+# ...
+
+volumes:
+  # A name for your volume.
+  # Must be unique for the given app.
+  - name: data
+    # Where to mount the volume into the filesystem.
+    # You can specify multiple mounts with optional subpaths.
+    mounts:
+      # Mount the volume to `/data`.
+      - mount_path: /data
+ # Optional: the subdirectory of the volume to mount.
+ # subpath: /subpath
+```
+
+This will create a new "data" volume, which will be mounted at `/data`.
+
+Now just re-deploy your app with `wasmer deploy`.
+The volume will be automatically created.
+
+Your application can now use the mount path and treat it as persistent storage.
+
+<Callout type="warning">
+The name of a volume acts as a unique identifier.
+If you change the name the old volume - including it's data - will be deleted!
+</Callout>
+
+### Deleting Volumes
+
+To delete a volume, simply remove it from your app configuration an re-deploy.
+The data will be purged, and your app will not have access to the volume anymore.
+
+## Inspecting Volumes
+
+You can inspect volumes in two ways:
+
+* in the web frontend on your app dashboard:
+  Go to the "Storage" tab - you will see a list of volumes with their size.
+* using the CLI:
+  Run `wasmer app volumes list [app]` to list all volumes and their sizes.
+
+## Remotely Accessing Volumes
+
+Volumes are not only available to your apps, but can also be remotely accessed
+through the standard S3 API, or through a builtin web UI.
+
+You can use the CLI to retrieve S3 credentials:
+
+```bash
+wasmer app volumes s3-credentials [app]
+```
+
+This will print the S3 API URL, access key and secret key.
+
+
+<Callout type="info">
+You can visit the above URL in your browser to access a builtin web UI!
+</Callout>
+
+### Configuring rclone
+
+[rclone](https://rclone.org/) is a popular CLI client that allows full access
+to your volumes. It even allows mounting a volume to your local machine!
+
+You can get an rclone configuration snippet through the CLI:
+
+```bash
+wasmer app volumes s3-credentials --rclone-print [app] 
+```
+
+This will print out a configuration snippet that can be added to the rclone
+configuration file.
+
+The config file is usually located at `~/.config/rclone/rclone.conf`, but you
+can retrieve the active path with `rclone config file`.
+
+Some examples of using rclone:
+
+(Note: replace <edge-my-app-name> with the name of the rclone target)
+
+```bash
+# List all volumes in this app:
+rclone lsd <target>:
+
+# List files in a given volume:
+rclone lsd <target>:<volume-name>
+
+# Copy a file to a volume:
+rclone copy ./local-filename <target>:<volume-name>/remote-filename
+
+# Mount a volume to a local directory
+mkdir my-volume
+rclone mount <target>:<volume-name> ./my-volume
+```