Skip to content

v1.0 - Initial Stable Release

Choose a tag to compare

View all tags
@pierre-b pierre-b released this 28 Nov 15:23
v1.0
2272a6a

selfhost_s3 v1.0

A minimal S3-compatible object storage server written in Go that persists files to the local filesystem. Designed for development and self-hosted deployments where a full S3 service is overkill.

Features

  • S3-compatible API with AWS Signature V4 authentication
  • Local filesystem storage - no external dependencies
  • Public file access - serve files without authentication via configurable prefix
  • Cache headers - configurable Cache-Control for public files
  • Download mode - force file download with ?download=1 query parameter
  • Multi-platform Docker images - supports amd64 and arm64

Supported S3 Operations

Operation Description
GetObject Download/serve files
HeadObject Check file metadata
PutObject Upload files
DeleteObject Delete files
ListObjectsV2 List bucket contents

Quick Start

docker run -d \
  --name selfhost_s3 \
  -p 9000:9000 \
  -v $(pwd)/data:/data \
  -e S3_BUCKET=my-bucket \
  -e S3_ACCESS_KEY=myaccesskey \
  -e S3_SECRET_KEY=mysecretkey \
  notifuse/selfhost_s3:v1.0

Configuration

Variable Required Default Description
S3_BUCKET Yes - S3 bucket name
S3_ACCESS_KEY Yes - Access key for authentication
S3_SECRET_KEY Yes - Secret key for authentication
S3_PORT No 9000 Port to listen on
S3_STORAGE_PATH No ./data Local directory for file storage
S3_REGION No us-east-1 AWS region (for signature validation)
S3_CORS_ORIGINS No * Allowed CORS origins
S3_MAX_FILE_SIZE No 100MB Maximum upload file size
S3_PUBLIC_PREFIX No public/ Prefix for public files (empty disables)
S3_PUBLIC_CACHE_MAX_AGE No 31536000 Cache-Control max-age for public files

Public File Access

Files under the public/ prefix can be accessed without authentication:

# Upload (requires auth)
aws s3 cp image.png s3://my-bucket/public/image.png --endpoint-url http://localhost:9000

# Access publicly (no auth)
curl http://localhost:9000/my-bucket/public/image.png

# Force download
curl http://localhost:9000/my-bucket/public/image.png?download=1

Docker Images

Available on Docker Hub:

  • notifuse/selfhost_s3:v1.0
  • notifuse/selfhost_s3:latest

Full documentation: README.md

Assets 2
Loading