MyS3

MyS3 is a minimal, open-source object store inspired by AWS S3. It exposes a JSON-only HTTP API, stores every object directly on the filesystem, and is designed to run anywhere Puma and Sinatra are available.

Just rent a Storage VPS and run your own Simple-Storage-Service for cheap.

• JSON-over-HTTP API with API-key authentication only
• Filesystem-backed storage with nested folders/prefixes
• Thread-safe operations compatible with Puma multi-threading
• Configurable upload limits, logging, timezone, and symlink policy
• Zero external services: no database, queues, or UI
• Lightweight landing page at / to confirm the daemon is live (no API key required)

• Ruby 3.1.2 (or newer 3.1.x)
• Bundler
• A writable directory for the storage root and log files

bundle install
cp config.example.yml config.yml
$EDITOR config.yml

Set MY_S3_CONFIG=/absolute/path/to/config.yml if the file lives outside the project root.

All configuration lives in config.yml and is never exposed through the API. The file must define the following keys:

Any relative paths are resolved against the configuration file directory. The application creates the storage root and log/ directory on boot when needed.

MY_S3_CONFIG=/srv/my_s3/config.yml bundle exec puma \
	-t 4:16 \
	-b tcp://0.0.0.0:4567 \
	config.ru

Always point Puma at config.ru; it bootstraps the Rack app and pulls in app.rb. Run the command from the repository root so Bundler picks up the correct Gemfile (or export BUNDLE_GEMFILE=/abs/path/to/Gemfile if you insist on running it elsewhere). Use the same host/port and thread counts configured in your config.yml. Puma’s multi-threaded mode is required; every disk operation is wrapped in thread-safe primitives inside the app.

Browsing to / in a web browser now shows the Explorer login: submit the API key once and the session cookie unlocks the UI. All JSON endpoints still require the X-API-Key header for every request.

Point your browser at / and enter the API key once to unlock a lightweight explorer UI. The key is stored in an encrypted session cookie so you can click through folders, review file metadata, download assets, open files in a new tab, and delete files or folders without crafting curl commands. Use the breadcrumb navigation to move around and the “Sign out” button to clear the session; closing the browser tab also invalidates the session cookie when it expires.

All endpoints:

• Require X-API-Key: <your api_key>
• Accept/return JSON (except upload.json, which uses multipart form data)

List everything at the root:

curl -H "X-API-Key: CHANGE_ME" \
  'http://127.0.0.1:4567/list.json?path='

Create a folder:

curl -X POST -H "Content-Type: application/json" \
	-H "X-API-Key: CHANGE_ME" \
	-d '{"path":"projects","folder_name":"images"}' \
	http://127.0.0.1:4567/create_folder.json

Upload a file (multipart):

curl -X POST -H "X-API-Key: CHANGE_ME" \
	-F path=projects/images \
	-F file=@./example.png \
	http://127.0.0.1:4567/upload.json

Delete files older than 30 days:

curl -X POST -H "Content-Type: application/json" \
	-H "X-API-Key: CHANGE_ME" \
	-d '{"path":"projects/images","older_than":"2025-01-01T00:00:00Z"}' \
	http://127.0.0.1:4567/delete_older_than.json

Generate a URL:

curl -X POST -H "Content-Type: application/json" \
	-H "X-API-Key: CHANGE_ME" \
	-d '{"path":"projects/images","filename":"example.png"}' \
	http://127.0.0.1:4567/get_public_url.json

• Logs are written to the path defined by log_file (defaults to log/app.log).
• Every unhandled exception is logged with a stack trace and surfaces as a 500 Internal Server Error JSON payload.
• Add your own metrics/forwarding by tailing the log file, shipping to Loki, etc.

• Run behind a TLS-terminating reverse proxy (nginx, Traefik, Caddy).
• Rotate the API key regularly and store it outside version control.
• Mount the storage root on durable disks (e.g., attached volume, network share).
• Create and monitor backups; objects live on disk only.
• Configure log rotation to keep disk usage predictable.

Enjoy!