.env.example

# MonoBucket configuration. Copy to `.env` and edit.
# Every setting is read once at startup; nothing here is hot-reloaded.
#
# Size values accept unit suffixes:
#   binary (1024-based) : K  Ki  KiB  M  Mi  MiB  G  Gi  GiB  T  Ti  TiB
#   SI     (1000-based) : KB  MB  GB  TB
# A bare number is bytes.

# --- Network ---------------------------------------------------------------
MONOBUCKET_HOST=0.0.0.0
MONOBUCKET_PORT=9000
MONOBUCKET_CONSOLE_PORT=9001
MONOBUCKET_CONSOLE_ENABLED=true

# --- Storage ---------------------------------------------------------------
# Must be an absolute path. Object payloads, metadata and upload temporaries
# all live underneath it.
MONOBUCKET_DATA_DIR=/data
MONOBUCKET_REGION=us-east-1

# Where the console's backup action may write. Unset — the default — disables
# that action entirely; `monobucket --checkpoint <dir>` is unaffected, because
# whoever runs it already has a shell on the host.
#
# A directory rather than a free path, because the destination arrives over
# HTTP. Backups are created inside it under a name the administrator chooses,
# and that name may not contain a path separator: a console session should not
# be able to create directories wherever the server can write.
#
# Put it on the same filesystem as MONOBUCKET_DATA_DIR if you can. Payloads are
# hard-linked, so a backup there duplicates no bytes and finishes almost
# immediately; anywhere else and the whole store is copied. Either way the copy
# is a complete data directory — stop the server, point MONOBUCKET_DATA_DIR at
# it, start, and you are restored.
# MONOBUCKET_BACKUP_DIR=/backups

# How much of a write must reach stable storage before it is acknowledged.
#   none    - no explicit flushing. Survives a process crash, not a power cut.
#             For CI and throwaway containers.
#   relaxed - fsync each payload before publishing it. The default.
#   strict  - also fsync the directory entry and the metadata log on every
#             commit. Survives a power cut, at the cost of an fsync per write.
MONOBUCKET_DURABILITY=relaxed

# Combined ceiling for the metadata store's block cache and write buffers.
# RocksDB sizes those independently by default and the container only sees the
# sum, so this is charged against both. Minimum 4MiB.
MONOBUCKET_METADATA_MEMORY_BYTES=32MiB

# Bounds the table-reader memory that open SST files pin. Unbounded, this grows
# with the object count for the lifetime of the process.
MONOBUCKET_METADATA_MAX_OPEN_FILES=256

# How long an unreferenced payload is left alone before the sweeper reclaims
# it. Must comfortably exceed the longest upload still in flight: a payload is
# tracked before it is written, so a short grace can reclaim a file a client is
# still uploading to. Minimum 60.
MONOBUCKET_RECLAIM_GRACE_SECONDS=3600

# How often the background sweeper runs. 0 disables it, leaving reclamation to
# the deletion path and to startup recovery.
MONOBUCKET_RECLAIM_INTERVAL_SECONDS=300

# How long a multipart upload may sit without a part arriving before the
# sweeper aborts it, releasing its parts and the allocation they were charged
# against. 0 disables the sweep.
#
# Worth understanding before changing: an abandoned upload is not garbage the
# reclamation sweeper above can collect. Its parts are properly referenced, so
# nothing treats them as unreferenced, and they stay on disk and stay charged
# to the bucket until somebody aborts the upload. A client that crashes
# mid-transfer never will. Without an expiry the only bound on that is an
# operator noticing.
#
# The default is deliberately generous. What decides is the most recent part,
# not when the upload began, so a slow client is safe for as long as it keeps
# making progress. Must be at least MONOBUCKET_RECLAIM_GRACE_SECONDS.
MONOBUCKET_MULTIPART_EXPIRY_HOURS=168

# The origin S3 clients reach this deployment at. Only the console reads it, to
# build object links and to sign presigned URLs — behind a reverse proxy the
# browser cannot work it out, because the console is served from a different
# hostname on a different port. Left unset, links point at the console's own
# hostname and MONOBUCKET_PORT, which is right only without a proxy.
# MONOBUCKET_S3_PUBLIC_URL=https://s3.example.com

# --- Storage allocations -----------------------------------------------------
# Every bucket created in the console is given an allocation, drawn from one
# instance-wide capacity. Left unset, that capacity is the filesystem holding
# MONOBUCKET_DATA_DIR less MONOBUCKET_CAPACITY_RESERVE_PERCENT — set it
# explicitly when the data directory shares its disk with anything else.
# MONOBUCKET_ALLOCATABLE_BYTES=500GiB
MONOBUCKET_CAPACITY_RESERVE_PERCENT=10

# What a bucket created by plain S3 CreateBucket gets, which has no field to ask
# for one. Zero leaves those buckets unlimited, which is what every bucket was
# before allocations existed.
MONOBUCKET_DEFAULT_BUCKET_QUOTA_BYTES=0

# --- Console administrator -------------------------------------------------
# Who signs in to the dashboard. This is a person's login and has nothing to do
# with the S3 credentials below: revoking an S3 key never locks you out of the
# console, and signing out never breaks a client.
#
# There is no default password. A deployment with no enabled administrator and
# no password here refuses to start, because the alternative is either a
# documented default — a published credential on every install that skipped the
# docs — or a console nobody can get into.
#
# This names the *first* account. Everyone else is created in the console under
# Users, with a role that bounds both what they can do there and what any S3
# access key they issue can do.
MONOBUCKET_ADMIN_USERNAME=admin

# Set exactly one of these, at least 12 characters. Prefer the _FILE form: a
# value in the environment is visible in `docker inspect`, in /proc/<pid>/environ
# and in the shell history of whoever started the container.
#
# Only needed to create or reset the account. Once it is provisioned the record
# lives in the data directory, so unset this again and the server still starts.
# Leaving it set means every restart resets the password to this value — and
# restores that account to an enabled administrator, which is what makes this
# the way back in after a role change nobody meant to make.
# MONOBUCKET_ADMIN_PASSWORD=
# MONOBUCKET_ADMIN_PASSWORD_FILE=/run/secrets/monobucket_admin_password

# Whether the session cookie carries `Secure`.
#   auto  - set it when the request arrived over TLS, directly or via a proxy
#           that sent X-Forwarded-Proto. The default, and almost always right.
#   true  - always. Only correct when every path to the console is HTTPS;
#           behind a plain-HTTP hop the browser accepts the cookie and then
#           refuses to send it, which looks like a login that does nothing.
#   false - never.
MONOBUCKET_CONSOLE_COOKIE_SECURE=auto

# --- Root S3 credentials ---------------------------------------------------
# The bootstrap S3 key pair, used to sign S3 requests and nothing else — it has
# not signed you in to the console since the administrator account existed.
# Change it before exposing the server; the secret must be >= 8 characters.
#
# Further key pairs are issued from the console's Access keys screen and stored
# in the data directory. This one cannot be revoked from there, so treat it as
# the break-glass credential and prefer issued keys for day-to-day clients.
MONOBUCKET_ROOT_ACCESS_KEY=monobucket
MONOBUCKET_ROOT_SECRET_KEY=change-me-before-production

# --- Runtime ---------------------------------------------------------------
# 0 derives the worker count from std::thread::hardware_concurrency().
MONOBUCKET_WORKER_THREADS=0

# Largest accepted single-part upload. Larger objects must use multipart.
MONOBUCKET_MAX_BODY_BYTES=5GiB

# Request bodies above this size spill to disk instead of being buffered in
# RAM. Lowering it lowers peak memory; raising it lowers small-object latency.
MONOBUCKET_MAX_MEMORY_BODY_BYTES=1MiB

# Largest object this instance accepts, whatever path it arrives by: the
# console uploader, a signed PUT, or a multipart upload measured across all of
# its parts. Unlike everything else here, this one is only a *seed* — it is
# stored in the metadata store on first start, and from then on the console
# owns it (Settings -> Maximum object size, administrator only). Changing this
# variable on a store that already carries a limit does nothing.
MONOBUCKET_MAX_UPLOAD_BYTES=5GiB

# The most the console may ever raise that limit to. Environment only, so an
# administrator cannot lift their own ceiling. 5 TiB is S3's own maximum object
# size, so the default constrains nothing S3 would have accepted.
MONOBUCKET_MAX_UPLOAD_CEILING_BYTES=5TiB

# Read/write granularity of the streaming I/O engine.
MONOBUCKET_STREAM_CHUNK_BYTES=1MiB

MONOBUCKET_IDLE_TIMEOUT_SECONDS=60

# --- I/O -------------------------------------------------------------------
# Blocking filesystem work runs on its own pool so it never occupies an event
# loop thread. 0 matches the worker thread count.
MONOBUCKET_IO_THREADS=0

# Queue depth before storage work is rejected outright. Bounded on purpose: an
# unbounded queue turns a disk that cannot keep up into unbounded memory.
MONOBUCKET_IO_QUEUE_LIMIT=1024

# --- Cache -----------------------------------------------------------------
# memory | redis
#
#   memory - a sharded LRU inside the process. The default, and the right
#            answer for a single container.
#   redis  - a shared cache for several instances, fronted by a local tier that
#            keeps serving if Redis goes away. Requires a binary built with
#            -DMONOBUCKET_ENABLE_REDIS=ON; otherwise the setting is ignored
#            with a warning and the in-memory backend is used.
MONOBUCKET_CACHE_BACKEND=memory

# Budget for the cache, counted as stored bytes plus per-entry overhead and
# held on every insert rather than trimmed later. 0 disables caching entirely;
# anything else must be at least 1MiB. With the redis backend, a quarter of
# this is the local tier and the rest lives in Redis.
MONOBUCKET_CACHE_MAX_BYTES=128MiB

# Default lifetime of a cached entry. 0 means "until evicted", which is safe
# for a single instance and not for a shared Redis.
MONOBUCKET_CACHE_TTL_SECONDS=300

# Ceiling on how long the local tier may hold a copy of a value that lives in
# Redis. Another instance can change it, and this is how long that can go
# unnoticed. Only meaningful with the redis backend.
MONOBUCKET_CACHE_LOCAL_TTL_SECONDS=5

# Required when the backend is redis.
#   redis://[user[:password]@]host[:port][/db]
# Percent escapes in the credentials are decoded, so a password containing '@'
# or ':' can be written as %40 / %3A. TLS (rediss://) is not supported.
#MONOBUCKET_REDIS_URL=redis://redis:6379

# Connections held open to Redis. Bounded on purpose: an unbounded pool turns a
# stalled Redis into unbounded file descriptors.
MONOBUCKET_REDIS_POOL_SIZE=4

# --- Observability ---------------------------------------------------------
# trace | debug | info | warn | error
MONOBUCKET_LOG_LEVEL=info
MONOBUCKET_METRICS_ENABLED=true