onifast-s3 — Onifast Docs

Object Storage Local Disk S3 Universal Proxy Image Resizing

onifast-s3 is a high-performance, Go-based object storage hub. It acts as both a local S3-compatible server (hosting buckets on disk) and a universal management proxy for external S3 providers like AWS S3 and MinIO.

A single combined server on port 4032 handles both S3 API protocol parameters and the Web Management GUI. It differentiates incoming traffic by inspecting target URI routes and Authorization request headers.

Universal S3 Storage

Local S3 Engine

Forks and hosts local client files securely on local disk structures using S3 APIs.

Universal S3 Explorer

Examine and manage AWS, MinIO, and other external accounts inside a unified portal.

Smart Thumbnail Engine

Serves on-the-fly thumbnail sizes by evaluating width variables (e.g. ?w=200).

Port Allocations

Port	Visibility	Description
4032	Internal Only	Combined engine: S3 API + Web Management GUI dashboard (proxied via panel as `/s3`)

Security Tip

Port 4032 is locked down for localhost access. The panel handles proxy routing directly to the local S3 hub. Once logged into the admin dashboard, access S3 Explorer interfaces using the https://your-domain:4050/s3 path.

System configuration database resides locally at /home/root/onifast/config/onifast-s3.db in full WAL write-ahead-logging structures:

🪣 buckets

name TEXT PRIMARY KEY
owner TEXT (panel user)
access_key TEXT
secret_key TEXT
created_at TIMESTAMP

📄 objects

bucket TEXT
key TEXT
size INTEGER
content_type TEXT
etag TEXT
last_modified TIMESTAMP

☁️ external_accounts

name TEXT PRIMARY KEY
bucket TEXT
access_key TEXT
secret_key TEXT
endpoint TEXT (AWS, MinIO, etc.)
owner TEXT

SSO Token Authentication (Recommended)

The web panel creates a high-entropy single-use token, redirecting browser clients to the /sso-login?token=<token> route. Authenticating happens silently in the background — no separate credentials are required.

Direct S3 Credentials Login

Clients can also bind directly to the web console by submitting their bucket’s access_key and secret_key credentials on the /login portal.

Trusted Local Proxy Mappings

Internal requests dialing from 127.0.0.1 containing the X-Onifast-User request header are auto-approved as the targeted username, letting panel integrations manipulate backend schemas without key handshakes.

REST JSON API Reference

Method	Path	Description
GET	`/view/{name}.{ext}?id={key}`	View file (inline). Supports smart resizing (e.g. `&w=200`)
GET	`/download/{name}.ext?id={key}`	Force download file
POST	`/upload`	Upload file via multipart payload
POST	`/delete`	Remove file from target bucket
POST	`/rename`	Rename/move file (instantly local; copy+delete external)
GET	`/` (browser)	Web Management GUI dashboard console
GET	`/external-accounts`	External AWS/MinIO accounts management dashboard

PHP Option A: Upload a File

Use multipart cURL requests to upload files directly into your local S3 bucket:

php

<?php
$postData = [
    'file'        => curl_file_create($filePath, $fileType, $fileName),
    'account'     => 'my-bucket',
    'token'       => 'your-secret-key',
    'path'        => 'uploads/'
];
$ch = curl_init('https://s3.your-domain.com/upload');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
// $response['status'] == 'success'
// $response['data']['url'] — view URL

PHP Option B: Delete a File

php

<?php
$ch = curl_init('https://s3.your-domain.com/delete');
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'account' => 'my-bucket',
    'token'   => 'your-secret-key',
    'id'      => 'uploads/old_file.jpg'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

S3 Configuration Keys

Parameters reside inside the global serverconfig.json:

Key Name	Description	Default Value
`s3_storage_path`	Local disk path for hosting S3 buckets (supports `{username}`)	`/home/{username}/.onifast/s3`
`s3_allow_create_bucket`	Allows standard users to build custom S3 buckets (bool)	`true`

Config Hot-reloads

S3 parses configuration hot-reloads every 5 seconds. Changes to serverconfig.json are applied instantly without service disruption.

Systemd Service Configuration

systemd

[Unit]
Description=Onifast S3 Storage
After=network.target

[Service]
ExecStart=/home/root/go/cmd/onifast-s3/onifast-s3
WorkingDirectory=/home/root/go/cmd/onifast-s3
Restart=always

[Install]
WantedBy=multi-user.target

🪣 onifast-s3