From 655e8f067496f2baf48c4e818bd0051bf51e3c40 Mon Sep 17 00:00:00 2001 From: Jonathan Visser Date: Fri, 13 Jun 2025 23:17:12 +0200 Subject: [PATCH] Improve Hypernode Object Storage CLI docs --- docs/hypernode-platform/object-storage.md | 2 + .../object-storage/basic-commands.md | 137 ++++++++++++++ .../object-storage/cancellation.md | 15 -- .../object-storage/dynamic-upscaling.md | 44 ++++- .../object-storage/getting-started.md | 6 + .../object-storage/interactive-explorer.md | 22 +++ .../object-storage/managing-objects.md | 175 +++++++++++++++--- 7 files changed, 359 insertions(+), 42 deletions(-) create mode 100644 docs/hypernode-platform/object-storage/basic-commands.md delete mode 100644 docs/hypernode-platform/object-storage/cancellation.md create mode 100644 docs/hypernode-platform/object-storage/interactive-explorer.md diff --git a/docs/hypernode-platform/object-storage.md b/docs/hypernode-platform/object-storage.md index 4851d89c..a1e599d3 100644 --- a/docs/hypernode-platform/object-storage.md +++ b/docs/hypernode-platform/object-storage.md @@ -31,3 +31,5 @@ glob: object-storage/getting-started object-storage/* ``` + +To get started with Hypernode Object Storage, check out our [Getting started](object-storage/getting-started.md) guide for a detailed overview of the system architecture and features. diff --git a/docs/hypernode-platform/object-storage/basic-commands.md b/docs/hypernode-platform/object-storage/basic-commands.md new file mode 100644 index 00000000..3065bbca --- /dev/null +++ b/docs/hypernode-platform/object-storage/basic-commands.md @@ -0,0 +1,137 @@ +--- +myst: + html_meta: + description: Learn about the basic commands for managing Hypernode Object Storage + title: Hypernode Object Storage | Basic Commands +--- + +# Basic Commands + +This guide covers the fundamental commands for managing your Hypernode Object Storage workspace. These commands allow you to create, view, update, and cancel your object storage workspace. + +## Creating a Workspace + +The `create` command initializes a new Object Storage workspace. + +```console +hypernode-object-storage create +``` + +### Options + +- `--name`: Specify a custom name for your workspace +- `--plan`: Select a storage plan (e.g., OS50GB, OS200GB) +- `--coupon`: Apply a coupon code for discounts + +### Example + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage create --name my-storage --plan OS200GB +``` + +## Viewing Workspace Information + +The `info` command displays details about your current Object Storage workspace. + +```console +hypernode-object-storage info +``` + +### Options + +- `--with-credentials`: Display sensitive credentials +- `--verbose`: Show detailed debug information +- `-F {text,json}`: Choose output format (text or JSON) + +### Example Output + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage info +UUID | d8770125-6c90-4770-b00f-1716f699990a +Name | example-storage +Plan | OS200GB +Versioning | Disabled +Hypernodes | example +Endpoint URL | **sensitive** +Access Key | **sensitive** +Secret Key | **sensitive** +``` + +### JSON Output Example + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage info -F json +{ + "UUID": "2667238b-9976-437f-98f5-cd7491b76fd8", + "Name": "my workspace", + "Plan": { + "code": "OS200GB", + "name": "Growth Node", + "description": "Great for expanding stores", + "price": 2000, + "storage_size_in_gb": 200, + "is_popular": true + }, + "Versioning": false, + "Hypernodes": "example", + "Credentials": { + "management_url": "**sensitive**", + "access_key": "**sensitive**", + "secret_key": "**sensitive**" + } +} +``` + +## Updating Workspace Settings + +The `update` command allows you to modify your Object Storage workspace settings. + +```console +hypernode-object-storage update +``` + +### Options + +- `--enable-versioning`: Enable object versioning +- `--disable-versioning`: Disable object versioning + +### Example + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage update --enable-versioning +Enabling versioning... +Versioning enabled successfully! +``` + +```{note} +Enabling versioning increases storage usage as each version of an object is stored separately. Consider your storage plan size when enabling this feature. +``` + +## Canceling a Workspace + +The `cancel` command initiates the cancellation process for your Object Storage workspace. + +```console +hypernode-object-storage cancel +``` + +### Important Notes + +1. **Cancellation Timing** + + - Cancellation takes effect at the end of the current billing period + - You will be billed for the full period + +1. **Data Retention** + + - Data remains accessible for 7 days after cancellation + - Use this period to retrieve any needed data + +### Example + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage cancel +Are you sure you want to cancel your Object Storage workspace? [y/N]: y +Cancellation initiated. Your workspace will be canceled at the end of the current billing period. +Data will remain accessible for 7 days after cancellation. +``` diff --git a/docs/hypernode-platform/object-storage/cancellation.md b/docs/hypernode-platform/object-storage/cancellation.md deleted file mode 100644 index aa983931..00000000 --- a/docs/hypernode-platform/object-storage/cancellation.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -myst: - html_meta: - description: Learn how to cancel Hypernode Object Storage - title: Hypernode Object Storage | Cancellation ---- - -# Cancellation - -To cancel an Object Storage Workspace, you can SSH into the Hypernode that is linked to that Object Storage and run `hypernode-object-storage cancel`. - -```{note} -The cancellation will be in effect from the end of the month. -Also if you change your mind or forgot to pull some data. It will still be available for 7 days after the cancellation. You can always reach out to the support team for help if that happens. -``` diff --git a/docs/hypernode-platform/object-storage/dynamic-upscaling.md b/docs/hypernode-platform/object-storage/dynamic-upscaling.md index 0428fe28..fdcced01 100644 --- a/docs/hypernode-platform/object-storage/dynamic-upscaling.md +++ b/docs/hypernode-platform/object-storage/dynamic-upscaling.md @@ -15,6 +15,46 @@ When Dynamic Upscaling is enabled, the system monitors your usage and upgrades y ## Managing Dynamic Upscaling -Dynamic Upscaling can be enabled or disabled through the Control Panel. +### Control Panel -Go to the Control Panel, select the Object Storage workspace you want to enable/disable Dynamic Upscaling for, and toggle the Dynamic Upscaling switch. +Dynamic Upscaling can be enabled or disabled through the Control Panel: + +1. Go to the Control Panel +1. Select the Object Storage workspace +1. Toggle the Dynamic Upscaling switch + +### Command Line Interface + +You can also manage Dynamic Upscaling using the CLI. First, ensure you have the basic commands set up as described in [Basic Commands](basic-commands.md#updating-workspace-settings). + +To enable Dynamic Upscaling: + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage update --enable-dynamic-upscaling +Enabling dynamic upscaling... +Dynamic upscaling enabled successfully! +``` + +To disable Dynamic Upscaling: + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage update --disable-dynamic-upscaling +Disabling dynamic upscaling... +Dynamic upscaling disabled successfully! +``` + +To check the current status of Dynamic Upscaling: + +```console +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage info +UUID | d8770125-6c90-4770-b00f-1716f699990a +Name | example-storage +Plan | OS200GB +Versioning | Disabled +Dynamic Upscaling | Enabled +Hypernodes | example +``` + +```{note} +When Dynamic Upscaling is enabled, your plan will automatically upgrade when you reach 99% of your current storage limit. This may result in higher costs, so monitor your usage regularly. +``` diff --git a/docs/hypernode-platform/object-storage/getting-started.md b/docs/hypernode-platform/object-storage/getting-started.md index 80bb122b..fccc8912 100644 --- a/docs/hypernode-platform/object-storage/getting-started.md +++ b/docs/hypernode-platform/object-storage/getting-started.md @@ -62,7 +62,13 @@ Secret Key | **sensitive** 1. Click your workspace. 1. Click the **Show credentials** button in the top-right corner. +## Setting up your application + You can use the credentials and the URL now to configure remote storage for your application with the help of the following articles: 1. [How to configure remote storage for Magento 2.x](../../ecommerce-applications/magento-2/how-to-configure-remote-storage-for-magento-2-x.md) 1. [How to configure remote storage for Shopware 6.x](../../ecommerce-applications/shopware-6/how-to-configure-remote-storage-for-shopware-6-x.md) + +## Setting up Nginx + +After setting up Object Storage, you will want to configure your Nginx to serve assets directly from your storage bucket. Learn how to do this using Hypernode Managed Vhosts in our [Object Storage and Hypernode Managed Vhosts](../nginx/hypernode-managed-vhosts.md#object-storage-and-hypernode-managed-vhosts) article. diff --git a/docs/hypernode-platform/object-storage/interactive-explorer.md b/docs/hypernode-platform/object-storage/interactive-explorer.md new file mode 100644 index 00000000..ce7ba7f6 --- /dev/null +++ b/docs/hypernode-platform/object-storage/interactive-explorer.md @@ -0,0 +1,22 @@ +--- +myst: + html_meta: + description: Learn how to use the interactive explorer of Hypernode Object Storage + title: Hypernode Object Storage | Interactive Explorer +--- + +# Interactive Explorer + +Hypernode Object Storage provides an interactive terminal interface for exploring and managing your objects. The `explore` command launches a user-friendly terminal UI that makes it easy to navigate through your storage, view object versions, and perform common operations. + +## Explore + +Launch the interactive explorer with: + +```console +hypernode-object-storage explore +``` + +This opens a terminal UI that looks like this: + +![](_res/stu_screenshot.png) diff --git a/docs/hypernode-platform/object-storage/managing-objects.md b/docs/hypernode-platform/object-storage/managing-objects.md index b008cef5..4009312c 100644 --- a/docs/hypernode-platform/object-storage/managing-objects.md +++ b/docs/hypernode-platform/object-storage/managing-objects.md @@ -1,56 +1,181 @@ --- myst: html_meta: - description: Learn how to manage objects in Hypernode Object Storage + description: Learn how to manage objects in Hypernode Object Storage using the + CLI title: Hypernode Object Storage | Managing Objects --- # Managing Objects -You can manage your objects using the `hypernode-object-storage objects` subcommand. -It supports all common operations--listing, copying, moving, and deleting files--while also allowing you to sync files in the background and monitor the progress of an ongoing sync. +The `hypernode-object-storage objects` command provides a comprehensive set of tools for managing your objects in storage. This guide covers all available subcommands and their usage. + +## Synchronizing Objects + +The `sync` command synchronizes files between a local directory and an object storage location. ```console -app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects --help -usage: hypernode-object-storage objects [-h] {sync,cp,ls,mv,rm,show} ... +hypernode-object-storage objects sync +``` -Manage objects in object storage +### Basic Usage -positional arguments: - {sync,cp,ls,mv,rm,show} - sync Synchronize files between a local directory and an object storage location - cp Copy a file or object from one location to another - ls List objects in an S3 bucket or folder - mv Move or rename a file or object - rm Delete an object from S3 - show Display the current status of an ongoing sync process +```console +# Sync local directory to object storage +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects sync /path/to/local/dir/ s3://bucket-name/path/ -options: - -h, --help show this help message and exit +# Sync object storage to local directory +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects sync s3://bucket-name/path/ /path/to/local/dir/ ``` -It is important to note that `hypernode-object-storage objects` supports all optional flags available in `aws s3`, allowing you to customize its behavior for advanced configurations. +### Advanced Options + +- `--exclude`: Exclude files matching pattern +- `--include`: Include only files matching pattern +- `--delete`: Delete files in destination not in source +- `--dryrun`: Show what would be done without making changes -## Syncing files and monitoring progress +### Progress Monitoring -Syncing files between your local directory and object storage is simple. Run the following command: +The sync process runs in the background. Monitor progress using the `show` command: ```console -app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects sync /example/local/path/ s3://example/bucket/uri/ -Syncing objects from /example/local/path/ to s3://example/bucket/uri/... +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects sync /media/ s3://main/media/ +Syncing objects from /media/ to s3://main/media/... Sync process started with PID 1234 in the background. + +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects show 1234 +Completed 9.7 GiB/~30.0 GiB (118.2 MiB/s) with ~5 file(s) remaining ``` -The `sync` operation runs in the background, and you can monitor its progress by using the `show` command, for example: +## Copying Objects + +The `cp` command copies files or objects between locations. ```console -app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects show 1234 -Completed 9.7 GiB/~30.0 GiB (118.2 MiB/s) with ~5 file(s) remaining (calculating...) +hypernode-object-storage objects cp +``` + +### Basic Copy Operations + +```console +# Copy single file +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects cp file.txt s3://main/dir/file.txt + +# Copy between object storage locations +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects cp s3://main/dir1/file.txt s3://main/dir2/file.txt +``` + +### Recursive Copying + +```console +# Copy entire directory +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects cp -r /path/to/dir/ s3://main/dir/ +``` + +### Pattern Matching + +```console +# Copy only specific file types +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects cp -r /path/to/dir/ s3://main/dir/ --exclude "*" --include "*.jpg" +``` + +## Listing Objects + +The `ls` command lists objects in an S3 bucket or folder. + +```console +hypernode-object-storage objects ls [path] +``` + +### Basic Listing + +```console +# List root directory +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects ls s3://main/ + +# List specific directory +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects ls s3://main/media/ +``` + +### Filtering and Sorting + +```console +# List only files +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects ls s3://main/ --recursive + +# List with details +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects ls s3://main/ --long +``` + +### Output Formatting + +```console +# JSON output +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects ls s3://main/ -F json +``` + +## Moving Objects + +The `mv` command moves or renames files and objects. + +```console +hypernode-object-storage objects mv +``` + +### Basic Move Operations + +```console +# Move single file +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects mv file.txt s3://main/dir/file.txt + +# Rename object +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects mv s3://main/oldname.txt s3://main/newname.txt +``` + +### Batch Operations + +```console +# Move multiple files +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects mv /path/to/files/* s3://main/dir/ +``` + +## Deleting Objects + +The `rm` command deletes objects from storage. + +```console +hypernode-object-storage objects rm +``` + +### Basic Delete Operations + +```console +# Delete single file +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects rm s3://main/file.txt + +# Delete with confirmation +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects rm s3://main/file.txt --force ``` -If you run the `show` command after the sync operation has finished, you’ll see output like this: +### Recursive Deletion + +```console +# Delete directory and contents +app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects rm s3://main/dir/ --recursive +``` + +### Troubleshooting + +If the process is not found: ```console app@abcdef-example-magweb-cmbl:~$ hypernode-object-storage objects show 1234 Process 1234 does not exist anymore ``` + +This could mean: + +- The operation completed successfully +- The process was terminated +- The PID was incorrect