fix(readme): refresh README with clearer feature documentation, UI screenshots, and client usage examples

2026-03-15 00:27:18 +00:00
parent 44f9a0181f
commit f2df14cb5b
4 changed files with 73 additions and 22 deletions
--- 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

--- 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,7 +299,7 @@ volumes:
  objstdata:
 ```

-### Image details
+### Image Details

 - **Base**: `alpine:edge` with Deno runtime
 - **Architectures**: `linux/amd64`, `linux/arm64`
@@ -264,7 +308,7 @@ volumes:
 - **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
--- 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'
 }
--- 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'
 }