From f2df14cb5ba6466af3fea092a61528d2d13df59c Mon Sep 17 00:00:00 2001 From: Juergen Kunz Date: Sun, 15 Mar 2026 00:27:18 +0000 Subject: [PATCH] fix(readme): refresh README with clearer feature documentation, UI screenshots, and client usage examples --- changelog.md | 7 +++ readme.md | 84 +++++++++++++++++++++++++++--------- ts/00_commitinfo_data.ts | 2 +- ts_web/00_commitinfo_data.ts | 2 +- 4 files changed, 73 insertions(+), 22 deletions(-) diff --git a/changelog.md b/changelog.md index 3fb3f71..c11fdb1 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,12 @@ # Changelog +## 2026-03-15 - 1.4.1 - fix(readme) +refresh README with clearer feature documentation, UI screenshots, and client usage examples + +- Adds newly documented UI capabilities such as inline code editing, PDF viewing, dark theme, and configuration overview +- Expands S3 usage examples with AWS CLI, Node.js/TypeScript, and Python boto3 snippets +- Improves README structure, section headings, linked dependency references, and screenshot coverage + ## 2026-03-14 - 1.5.0 - feat(core) rebrand from s3container to objectstorage diff --git a/readme.md b/readme.md index 79c11ad..dccd355 100644 --- a/readme.md +++ b/readme.md @@ -1,27 +1,30 @@ # @lossless.zone/objectstorage -> S3-compatible object storage server with a slick management UI — powered by [`smartstorage`](https://code.foss.global/push.rocks/smartstorage). +> 🚀 S3-compatible object storage server with a slick management UI — powered by [`smartstorage`](https://code.foss.global/push.rocks/smartstorage). **objectstorage** gives you a fully featured, self-hosted S3-compatible storage server with a beautiful web-based management interface — all in a single Docker image. No Java, no bloat, no fuss. -Built on Deno for the backend and `@design.estate/dees-catalog` for a polished UI, it speaks the S3 protocol out of the box while adding powerful management features on top. +Built on Deno for the backend and [`@design.estate/dees-catalog`](https://code.foss.global/design.estate/dees-catalog) for a polished UI, it speaks the S3 protocol out of the box while adding powerful management features on top. ## Issue Reporting and Security For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly. -## Features +## ✨ Features - **Full S3 API compatibility** — Works with any S3 client, SDK, or tool (AWS CLI, boto3, etc.) - **Management UI** — Web dashboard for buckets, objects, policies, credentials, and server config - **Finder-style object browser** — Column view with file preview, drag-and-drop upload, move/rename, context menus +- **Inline code editing** — Built-in Monaco editor with syntax highlighting and save-back-to-storage +- **PDF viewer** — Render PDFs inline with page navigation, zoom, and thumbnails - **Named policy management** — Create reusable IAM-style policies, attach them to multiple buckets - **Credential management** — Add/remove access keys through the UI with live-reload - **Single Docker image** — Multi-arch (`amd64` + `arm64`), tiny Alpine-based image - **Fast** — Rust-powered storage engine via `smartstorage`, Deno runtime for management layer - **Secure by default** — JWT-based admin auth, S3 SigV4 authentication, bucket policies +- **🌙 Dark theme** — Automatic dark mode following your system preference -## Quick Start +## ⚡ Quick Start ### Docker (recommended) @@ -52,7 +55,7 @@ pnpm run build deno run --allow-all mod.ts server --ephemeral ``` -## Configuration +## ⚙️ Configuration objectstorage is configured through environment variables, CLI flags, or programmatic config. **Environment variables take precedence** over CLI flags. @@ -80,7 +83,7 @@ Options: --ephemeral Use ./.nogit/objstdata for storage (dev mode) ``` -## Management UI +## 🖥️ Management UI The web-based management UI is served on the UI port (default: `3000`). Log in with username `admin` and the configured admin password. @@ -102,6 +105,10 @@ Finder-style column browser for objects. Upload, download, preview, move, rename ![Browser](./docs/03-browser.png) +Right-click any item for quick actions: + +![Context Menu](./docs/11-context-menu.png) + #### Inline Code Editing Click Edit on any text file to open the built-in Monaco editor with syntax highlighting, language detection, and save-back-to-storage. @@ -138,13 +145,19 @@ Click "Add Key" to create new access credentials. They're immediately available ![Add Access Key](./docs/09-add-access-key.png) +### Configuration + +View your server's current configuration at a glance — ports, region, storage directory, and auth/CORS status. + +![Configuration](./docs/06-config.png) + ### Dark Theme Full dark theme support — automatically follows your system preference via `prefers-color-scheme`. ![Dark Theme](./docs/10-dark-theme.png) -## Named Policy System +## 📋 Named Policy System objectstorage adds a **named policy** abstraction on top of standard S3 bucket policies. Instead of editing raw JSON per bucket, you define reusable policy templates and attach them to any number of buckets. @@ -178,9 +191,11 @@ This lets one policy like "Public Read" work across many buckets without hardcod - **Deleting a policy** detaches it from all buckets and recomputes each - **Deleting a bucket** cleans up its policy attachments automatically -## S3 API Usage +## 🔌 S3 API Usage -Use any S3-compatible client to interact with the storage. Here's an example with the AWS CLI: +Use any S3-compatible client to interact with the storage. Here are some examples: + +### AWS CLI ```bash # Configure AWS CLI @@ -204,7 +219,7 @@ aws --endpoint-url http://localhost:9000 s3 cp s3://my-bucket/myfile.txt ./downl ### Node.js / TypeScript (AWS SDK v3) ```typescript -import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; +import { S3Client, PutObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3'; const s3 = new S3Client({ endpoint: 'http://localhost:9000', @@ -216,14 +231,43 @@ const s3 = new S3Client({ forcePathStyle: true, }); +// Upload an object await s3.send(new PutObjectCommand({ Bucket: 'my-bucket', Key: 'hello.txt', Body: 'Hello, S3!', })); + +// List objects in a bucket +const result = await s3.send(new ListObjectsV2Command({ + Bucket: 'my-bucket', +})); +console.log(result.Contents); ``` -## Docker +### Python (boto3) + +```python +import boto3 + +s3 = boto3.client( + 's3', + endpoint_url='http://localhost:9000', + aws_access_key_id='admin', + aws_secret_access_key='admin', + region_name='us-east-1', +) + +# Upload a file +s3.put_object(Bucket='my-bucket', Key='hello.txt', Body=b'Hello from Python!') + +# List objects +response = s3.list_objects_v2(Bucket='my-bucket') +for obj in response.get('Contents', []): + print(obj['Key'], obj['Size']) +``` + +## 🐳 Docker ### Build @@ -255,16 +299,16 @@ volumes: objstdata: ``` -### Image details +### Image Details - **Base**: `alpine:edge` with Deno runtime - **Architectures**: `linux/amd64`, `linux/arm64` -- **Size**: ~150MB compressed +- **Size**: ~150 MB compressed - **Init system**: `tini` for proper signal handling - **Exposed ports**: `9000` (S3), `3000` (UI) - **Volume**: `/data` — all bucket data and config persisted here -## Architecture +## 🏗️ Architecture ``` ┌─────────────────────────────────────────────────┐ @@ -300,15 +344,15 @@ volumes: | Layer | Technology | |---|---| -| **Storage Engine** | `@push.rocks/smartstorage` (Rust binary via `ruststorage`) | +| **Storage Engine** | [`@push.rocks/smartstorage`](https://code.foss.global/push.rocks/smartstorage) (Rust binary via `ruststorage`) | | **Runtime** | Deno | -| **Management API** | `@api.global/typedrequest` + `@api.global/typedserver` | -| **Auth** | JWT via `@push.rocks/smartjwt`, S3 SigV4 | -| **Frontend** | `@design.estate/dees-element` (LitElement) + `@design.estate/dees-catalog` | -| **Frontend Build** | esbuild via `@git.zone/tsbundle` | +| **Management API** | [`@api.global/typedrequest`](https://code.foss.global/api.global/typedrequest) + [`@api.global/typedserver`](https://code.foss.global/api.global/typedserver) | +| **Auth** | JWT via [`@push.rocks/smartjwt`](https://code.foss.global/push.rocks/smartjwt), S3 SigV4 | +| **Frontend** | [`@design.estate/dees-element`](https://code.foss.global/design.estate/dees-element) (LitElement) + [`@design.estate/dees-catalog`](https://code.foss.global/design.estate/dees-catalog) | +| **Frontend Build** | esbuild via [`@git.zone/tsbundle`](https://code.foss.global/git.zone/tsbundle) | | **Docker** | Multi-stage (Node.js build → Alpine + Deno runtime) | -## Development +## 🛠️ Development ```bash # Install dependencies diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index b52a95c..af65736 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@lossless.zone/objectstorage', - version: '1.4.0', + version: '1.4.1', description: 'object storage server with management UI powered by smartstorage' } diff --git a/ts_web/00_commitinfo_data.ts b/ts_web/00_commitinfo_data.ts index b52a95c..af65736 100644 --- a/ts_web/00_commitinfo_data.ts +++ b/ts_web/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@lossless.zone/objectstorage', - version: '1.4.0', + version: '1.4.1', description: 'object storage server with management UI powered by smartstorage' }