Configuration

Cloodsy S3 runs with sensible defaults and requires no configuration file. To customize, create a config.yaml file and pass it when starting the server:

./cloodsys3 serve -config config.yaml

Full Configuration Reference

Below is a complete config.yaml with all available options and their defaults:

server:
  listen: ":9000"             # Address to listen on (e.g. ":9000", "127.0.0.1:9000")
  region: "us-east-1"        # AWS region reported by GetBucketLocation
  cors_origins:              # Allowed CORS origins for browser-based S3 clients
    - "*"
  tls:
    enabled: false           # Enable HTTPS
    cert_file: ""            # Path to TLS certificate (PEM)
    key_file: ""             # Path to TLS private key (PEM)

database:
  path: "./.cloodsys3/cloodsys3.db"   # SQLite database file location
  busy_timeout: 5000                   # Write lock wait time in milliseconds
  cache_size: 64000                    # SQLite page cache size in KB (64MB)
  mmap_size: 134217728                 # Memory-mapped I/O in bytes (128MB)
  max_readers: 4                       # Parallel read connections

storage:
  root_dir: "./.cloodsys3/data"       # Default storage directory for all buckets
  multipart_max_age: "24h"            # Auto-cleanup incomplete multipart uploads
  lifecycle_interval: "1h"            # How often to check lifecycle expiration rules

logging:
  level: "info"              # Log level: debug, info, warn, error
  format: "text"             # Log format: text (human-readable) or json

admin:
  enabled: false             # Enable Admin REST API (separate HTTP server)
  listen: ":9001"            # Admin API listen address
  cors_origins:              # CORS origins for the Admin API
    - "*"

You only need to include the settings you want to change. Missing fields use the defaults shown above.

Configuration Sections

Server

The server section controls the S3 API server:

Key	Default	Description
`listen`	`:9000`	Address and port to bind. Use `127.0.0.1:9000` to restrict to localhost.
`region`	`us-east-1`	Region reported by `GetBucketLocation`. Set to match your AWS CLI config.
`cors_origins`	—	List of allowed CORS origins. Set to `["*"]` for browser-based access.

TLS / HTTPS

Enable TLS to serve over HTTPS without a reverse proxy:

server:
  tls:
    enabled: true
    cert_file: "/etc/ssl/certs/cloodsy.pem"
    key_file: "/etc/ssl/private/cloodsy.key"

When TLS is enabled, the server also sets Strict-Transport-Security (HSTS) headers.

Database

The database section tunes SQLite performance:

Key	Default	Description
`path`	`./.cloodsys3/cloodsys3.db`	Database file location. Created automatically if it doesn't exist.
`busy_timeout`	`5000`	Milliseconds to wait for a write lock before returning `SQLITE_BUSY`.
`cache_size`	`64000`	Page cache size in KB. Higher values improve read performance.
`mmap_size`	`134217728`	Memory-mapped I/O size in bytes (128MB default). Set to `0` to disable.
`max_readers`	`4`	Number of parallel read connections. Increase for read-heavy workloads.

The database uses WAL (Write-Ahead Logging) mode, which allows the server and CLI to access the database simultaneously without locking conflicts.

Recommended tuning for high-load servers:

database:
  busy_timeout: 10000        # 10 seconds for busy servers
  cache_size: 128000         # 128MB cache
  mmap_size: 268435456       # 256MB mmap
  max_readers: 8             # More parallel readers

Storage

The storage section controls where object data is stored:

Key	Default	Description
`root_dir`	`./.cloodsys3/data`	Default storage directory. Each bucket creates a subdirectory here.
`multipart_max_age`	`24h`	Incomplete multipart uploads older than this are automatically deleted.
`lifecycle_interval`	`1h`	How often the background cleaner checks for expired objects.

Per-bucket storage directories can override root_dir for individual buckets:

# Hot data on SSD
./cloodsys3 bucket create hot-data --storage-dir=/mnt/ssd

# Archives on HDD
./cloodsys3 bucket create archives --storage-dir=/mnt/hdd

Objects are stored with a .cloodsys3ext extension for security. The directory structure mirrors the object key hierarchy:

.cloodsys3/data/
└── my-bucket/
    ├── file.txt.cloodsys3ext
    └── photos/
        └── vacation.jpg.cloodsys3ext

Logging

Key	Default	Description
`level`	`info`	Minimum log level: `debug`, `info`, `warn`, `error`
`format`	`text`	Output format: `text` (human-readable, colored) or `json` (structured)

Use json format for log aggregation with tools like Loki, Elasticsearch, or CloudWatch:

logging:
  level: "info"
  format: "json"

Admin API

The Admin REST API provides a JSON-based management interface on a separate port. This is required for the Cloodsy S3 GUI app.

Key	Default	Description
`enabled`	`false`	Set to `true` to start the Admin API server.
`listen`	`:9001`	Admin API listen address (separate from S3 port).
`cors_origins`	`["*"]`	Allowed CORS origins. Restrict in production.

admin:
  enabled: true
  listen: ":9001"
  cors_origins:
    - "https://admin.example.com"

Before using the Admin API, create at least one admin user:

./cloodsys3 admin create myadmin

Example Configurations

Minimal (development)

No config file needed. Just run:

./cloodsys3 serve

This starts the S3 API on :9000 with storage in ./.cloodsys3/.

Production server

server:
  listen: ":443"
  region: "eu-west-1"
  tls:
    enabled: true
    cert_file: "/etc/ssl/certs/s3.example.com.pem"
    key_file: "/etc/ssl/private/s3.example.com.key"

database:
  path: "/var/lib/cloodsys3/cloodsys3.db"
  busy_timeout: 10000
  cache_size: 128000
  max_readers: 8

storage:
  root_dir: "/var/lib/cloodsys3/data"
  lifecycle_interval: "30m"

logging:
  level: "info"
  format: "json"

admin:
  enabled: true
  listen: "127.0.0.1:9001"
  cors_origins:
    - "https://admin.example.com"

Raspberry Pi

server:
  listen: ":9000"

database:
  path: "/home/pi/cloodsys3/cloodsys3.db"
  cache_size: 16000          # 16MB — conserve RAM
  mmap_size: 33554432        # 32MB mmap
  max_readers: 2             # Fewer readers on limited CPU

storage:
  root_dir: "/mnt/usb/s3-data"
  multipart_max_age: "12h"

logging:
  level: "warn"              # Reduce log noise

Multi-disk setup

storage:
  root_dir: "/mnt/hdd/default-storage"

Then assign individual buckets to different disks via CLI:

./cloodsys3 bucket create uploads --storage-dir=/mnt/ssd/uploads
./cloodsys3 bucket create backups --storage-dir=/mnt/hdd/backups
./cloodsys3 bucket create media --storage-dir=/mnt/nvme/media

Data Directory Structure

When the server starts, it creates the following structure:

.cloodsys3/
├── cloodsys3.db            # SQLite metadata database
├── cloodsys3.db-wal        # Write-ahead log (normal, auto-managed)
├── cloodsys3.db-shm        # Shared memory (normal, auto-managed)
└── data/                   # Default object storage
    ├── my-bucket/
    │   ├── file.txt.cloodsys3ext
    │   └── photos/
    │       └── image.jpg.cloodsys3ext
    └── another-bucket/
        └── ...

Custom storage directories exist outside this structure:

/mnt/ssd/hot-bucket/
    └── data.bin.cloodsys3ext

/mnt/hdd/archive-bucket/
    └── archive.tar.cloodsys3ext