Storage

MolnOS Storage provides a simple, S3-like object storage system for files, documents, media, and any binary data. Organize objects in buckets with hierarchical folder-like navigation using prefixes.

Don’t forget to register and start the service

Any service you want to use must be registered and started before using it. Also note that services may require other services to run—expect Databases to be needed by some other services.

Features

Bucket Management

Create and manage storage buckets to organize your objects. Each bucket is an isolated container with its own namespace.

Object Upload & Retrieval

Store and retrieve objects of any type - text files, images, videos, JSON documents, and binary data. Supports multiple upload methods:

• JSON upload for text content
• Binary upload with query parameters
• Multipart form upload for file uploads

Hierarchical Navigation

Navigate objects using S3-style prefix filtering. The system creates virtual folders from common prefixes, allowing you to browse storage like a traditional file system while maintaining the simplicity of a flat key-value structure.

Object Metadata

Each object includes metadata: size, last modification time, and type (file or folder). Track when objects were created and how much space they consume.

Bucket Statistics

View bucket-level statistics including total object count and total storage size.

Common Use Cases

• User Uploads: Store profile pictures, documents, and user-generated content
• Static Assets: Host images, videos, and media files for web applications
• Backups: Store database backups, configuration snapshots, and archives
• Log Archives: Archive old log files and audit trails
• Document Management: Organize and store business documents, contracts, and files
• CDN Origin: Use as origin storage for content delivery networks
• Data Lake: Store raw data for analytics and processing pipelines

How It Works

Console

You can create both public and private buckets in MolnOS. To create a bucket, just click the button, add the bucket a name, decide if the bucket should be public or not, and you are done.

To upload a file (or more), select them and add an optional path. If not providing a path, files will be created relative to the current “location” in the bucket.

Like in S3 and similar services, you can virtually navigate the paths of a bucket. From here you can also copy a link (if public), download, and delete a file (aka. “object”) from the bucket.

API

Storage is managed through the HTTP API at /storage/* endpoints.

List Buckets

GET /storage/buckets

Returns all storage buckets:

{
  "buckets": ["my-bucket-1", "my-bucket-2", "my-bucket-3"]
}

Create Bucket

POST /storage/buckets/{bucket}

Creates a new bucket with the specified name. Optionally configure public access and associate with a context:

{
  "public": false,
  "context": "my-app"
}

Parameters:

• public (optional) - Whether the bucket should be public (default: false)
• context (optional) - Context name to associate this bucket with for organizational grouping

Get Bucket Statistics

GET /storage/buckets/{bucket}

Returns bucket statistics:

{
  "bucket": "my-bucket",
  "objectCount": 42,
  "totalSize": 1048576,
  "public": false
}

Update Bucket

PATCH /storage/buckets/{bucket}

Update bucket configuration (e.g., make it public or private):

{
  "public": true
}

Response:

{
  "success": true,
  "bucket": "my-bucket",
  "public": true
}

Delete Bucket

DELETE /storage/buckets/{bucket}

Deletes a bucket (must be empty).

List Objects in Bucket

GET /storage/buckets/{bucket}/objects?prefix=docs/

Lists objects with hierarchical navigation:

{
  "objects": [
    {
      "key": "subfolder/",
      "size": 0,
      "lastModified": "2025-12-19T13:45:00.000Z",
      "type": "folder"
    },
    {
      "key": "readme.md",
      "size": 5678,
      "lastModified": "2025-12-19T13:45:00.000Z",
      "type": "file"
    }
  ],
  "prefix": "docs/"
}

Prefix Filtering Examples:

• No prefix: Shows root level (files + virtual folders)
• docs/: Shows immediate children under docs/
• docs/api/: Shows immediate children under docs/api/

Upload Object

PUT /storage/buckets/{bucket}/objects

Method 1 - JSON upload (text content):

{
  "key": "documents/readme.txt",
  "content": "Hello, World!"
}

Method 2 - Binary upload with query param:

PUT /storage/buckets/{bucket}/objects?key=images/photo.jpg
Content-Type: application/octet-stream

[binary data]

Method 3 - Multipart form upload:

PUT /storage/buckets/{bucket}/objects
Content-Type: multipart/form-data

key: images/photo.jpg
file: [file data]

Get Object

POST /storage/buckets/{bucket}/objects

Retrieve an object:

{
  "key": "documents/readme.txt"
}

Response:

{
  "bucket": "my-bucket",
  "key": "documents/readme.txt",
  "content": "Hello, World!"
}

Delete Object

DELETE /storage/buckets/{bucket}/objects

Delete an object:

{
  "key": "documents/readme.txt"
}

CLI

Storage operations using the MolnOS CLI:

# List all buckets
molnos storage buckets

# Create bucket (private by default)
molnos storage bucket create my-bucket

# Create public bucket
molnos storage bucket create my-bucket --public

# Get bucket statistics
molnos storage bucket get my-bucket

# Update bucket (e.g., make it public)
molnos storage bucket update my-bucket public=true

# Delete bucket
molnos storage bucket delete my-bucket

# List objects in bucket
molnos storage objects list my-bucket

# List objects with prefix (hierarchical navigation)
molnos storage objects list my-bucket docs/

# Upload text content to object
molnos storage object put my-bucket documents/readme.txt "Hello, World!"

# Upload file to object
molnos storage object upload my-bucket images/photo.jpg /path/to/local/photo.jpg

# Get/download object
molnos storage object get my-bucket documents/readme.txt

# Delete object
molnos storage object delete my-bucket documents/readme.txt

Permissions

Storage requires appropriate permissions to manage buckets and objects:

• storage.bucket.create - Create new buckets
• storage.bucket.list - List buckets
• storage.bucket.read - View bucket statistics
• storage.bucket.update - Update bucket configuration (public/private settings)
• storage.bucket.delete - Delete buckets
• storage.object.write - Upload objects to buckets
• storage.object.read - Download and view objects directly
• storage.object.list - List objects in buckets
• storage.object.delete - Delete objects from buckets

Fine-grained permissions can target specific buckets:

• storage.bucket.list:my-bucket - List specific bucket
• storage.bucket.read:my-bucket - Read statistics for specific bucket
• storage.object.write:my-bucket - Write access to specific bucket
• storage.object.list:my-bucket - List objects in specific bucket