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.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

✨ 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

Docker (recommended)

docker run -d \
  --name objectstorage \
  -p 9000:9000 \
  -p 3000:3000 \
  -v objstdata:/data \
  -e OBJST_ACCESS_KEY=myadminkey \
  -e OBJST_SECRET_KEY=mysupersecret \
  -e OBJST_ADMIN_PASSWORD=myuipassword \
  code.foss.global/lossless.zone/objectstorage:latest

Then open http://localhost:3000 for the management UI and use http://localhost:9000 as your S3 endpoint.

Deno (development)

# Clone and install frontend dependencies
git clone ssh://git@code.foss.global:29419/lossless.zone/objectstorage.git
cd objectstorage
pnpm install
pnpm run build

# Run in ephemeral mode (data stored in .nogit/objstdata)
deno run --allow-all mod.ts server --ephemeral

⚙️ Configuration

objectstorage is configured through environment variables, CLI flags, or programmatic config. Environment variables take precedence over CLI flags.

Environment Variables

Variable	Description	Default
`OBJST_PORT`	Storage API port	`9000`
`UI_PORT`	Management UI port	`3000`
`OBJST_STORAGE_DIR`	Data storage directory	`/data`
`OBJST_ACCESS_KEY`	Access key ID	`admin`
`OBJST_SECRET_KEY`	Secret access key	`admin`
`OBJST_ADMIN_PASSWORD`	Admin UI password	`admin`
`OBJST_REGION`	Storage region identifier	`us-east-1`

CLI Flags

deno run --allow-all mod.ts server [options]

Options:
  --storage-port <port>  Storage API port (default: 9000)
  --ui-port <port>       Management UI port (default: 3000)
  --storage-dir <path>   Storage directory (default: /data)
  --ephemeral            Use ./.nogit/objstdata for storage (dev mode)

🖥️ 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.

Overview

Dashboard showing server status, uptime, storage usage, bucket count, and connection info.

Buckets

Create/delete buckets. View object counts and sizes. Attach/detach named policies per bucket.

Browser

Finder-style column browser for objects. Upload, download, preview, move, rename, and delete files and folders — with syntax-highlighted code preview.

Right-click any item for quick actions:

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.

PDF Viewer

PDF files render inline with a full-featured viewer — page navigation, zoom, fit-to-page, thumbnails, download, and print.

Policies

Create reusable named policies with IAM-style S3 statements. Attach policies to multiple buckets at once.

Attaching Policies to Buckets

From the Buckets view, click the policy icon on any bucket to see attached and available policies. Attach or detach with one click.

Access Keys

Add and remove access credentials. Secret keys are masked. Changes take effect immediately — no server restart needed.

Adding Access Keys

Click "Add Key" to create new access credentials. They're immediately available for API authentication.

Configuration

View your server's current configuration at a glance — ports, region, storage directory, and auth/CORS status.

Dark Theme

Full dark theme support — automatically follows your system preference via prefers-color-scheme.

📋 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.

How it works

Create a named policy in the Policies view — give it a name, description, and S3 policy statements
Attach it to buckets — from the Policies view or the Buckets view
objectstorage merges all attached policy statements into a single S3 policy document and applies it to the bucket automatically

`${bucket}` placeholder

Use ${bucket} in your policy's Resource ARN and it will be replaced with the actual bucket name when applied:

[
  {
    "Sid": "PublicRead",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::${bucket}/*"
  }
]

This lets one policy like "Public Read" work across many buckets without hardcoding names.

Lifecycle

Updating a policy automatically recomputes and re-applies the merged S3 policy on all attached buckets
Deleting a policy detaches it from all buckets and recomputes each
Deleting a bucket cleans up its policy attachments automatically

🔌 S3 API Usage

Use any S3-compatible client to interact with the storage. Here are some examples:

AWS CLI

# Configure AWS CLI
aws configure set aws_access_key_id admin
aws configure set aws_secret_access_key admin
aws configure set default.region us-east-1

# Create a bucket
aws --endpoint-url http://localhost:9000 s3 mb s3://my-bucket

# Upload a file
aws --endpoint-url http://localhost:9000 s3 cp myfile.txt s3://my-bucket/

# List objects
aws --endpoint-url http://localhost:9000 s3 ls s3://my-bucket/

# Download a file
aws --endpoint-url http://localhost:9000 s3 cp s3://my-bucket/myfile.txt ./downloaded.txt

Node.js / TypeScript (AWS SDK v3)

import { S3Client, PutObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';

const s3 = new S3Client({
  endpoint: 'http://localhost:9000',
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'admin',
    secretAccessKey: 'admin',
  },
  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);

Python (boto3)

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

# Build for the native platform
pnpm run build:docker

# Or build and run directly
pnpm run start:docker

Docker Compose

services:
  objectstorage:
    image: code.foss.global/lossless.zone/objectstorage:latest
    ports:
      - "9000:9000"  # S3 API
      - "3000:3000"  # Management UI
    volumes:
      - objstdata:/data
    environment:
      OBJST_ACCESS_KEY: myadminkey
      OBJST_SECRET_KEY: mysupersecret
      OBJST_ADMIN_PASSWORD: securepw123

volumes:
  objstdata:

Image Details

Base: alpine:edge with Deno runtime
Architectures: linux/amd64, linux/arm64
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

┌─────────────────────────────────────────────────┐
│                objectstorage                     │
│                                                  │
│  ┌──────────────┐     ┌───────────────────────┐ │
│  │  Management   │     │   Storage Engine      │ │
│  │  UI (port     │     │  (smartstorage/       │ │
│  │   3000)       │     │   ruststorage)        │ │
│  │              │     │   (port 9000)         │ │
│  │  dees-catalog │     │  • S3 API compat      │ │
│  │  SPA bundle   │     │  • SigV4 auth         │ │
│  └──────┬───────┘     │  • Bucket policies    │ │
│         │              │  • Rust binary engine  │ │
│  ┌──────▼───────┐     └───────────────────────┘ │
│  │  OpsServer    │                               │
│  │  (TypedReq    │──── AWS SDK S3 Client ────────│
│  │   handlers)   │     (manages own storage)     │
│  │              │                               │
│  │  • Admin auth │                               │
│  │  • CRUD APIs  │                               │
│  │  • Policy mgr │                               │
│  └──────────────┘                               │
│                                                  │
│  ┌──────────────────────────────────────────────┐│
│  │           /data (persistent volume)          ││
│  │  buckets/  .policies/  .objectstorage/       ││
│  └──────────────────────────────────────────────┘│
└─────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Storage Engine	`@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`
Docker	Multi-stage (Node.js build → Alpine + Deno runtime)

🛠️ Development

# Install dependencies
pnpm install

# Watch mode — auto-rebuilds frontend + restarts backend
pnpm run watch

# Build frontend bundle only
pnpm run build

# Type check backend
deno check mod.ts

# Run in development mode
deno run --allow-all mod.ts server --ephemeral

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@lossless.zone/objectstorage