Update packaging/rustbox.toml

packaging/rustbox.toml

@@ -1,87 +1,363 @@
 # RustBox 0.2.0 - packaged production configuration (DEB/RPM)
+#
+# This file contains all supported RustBox configuration options.
+# Commented options are optional and do not change the packaged defaults.
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
 
 host = "0.0.0.0"
 port = 3001
 environment = "production"
+
 data_dir = "/var/lib/rustbox"
 log_dir = "/var/log/rustbox"
+
+# trace | debug | info | warn | error | off
+# RUST_LOG overrides this value when set.
 log_level = "warn"
 
+# Optional reverse-proxy subpath, e.g. "/mail".
+# base_path = "/mail"
+
+
+# -----------------------------------------------------------------------------
+# UI defaults
+# -----------------------------------------------------------------------------
+
+# system | dark | light
+default_theme = "system"
+
+# Built-in examples:
+# gmail, proton, zoho, outlook, fastmail, apple-mail, yahoo, hey,
+# nord, github, gitlab, discord, slack, reddit, notion, minimal,
+# and Roundcube variants.
+default_interface_skin = "apple-mail"
+
+
+# -----------------------------------------------------------------------------
+# Database
+# -----------------------------------------------------------------------------
+
+# sqlite | mysql | pgsql
 database_backend = "sqlite"
-session_backend = "database"
+
+# SQLite defaults to data_dir/rustbox.sqlite.
+# MySQL/PostgreSQL require database_url.
+#
+# PostgreSQL:
+# database_url = "postgres://rustbox:secret@db.example.com/rustbox"
+#
+# MySQL:
+# database_url = "mysql://rustbox:secret@db.example.com/rustbox"
+
+
+# -----------------------------------------------------------------------------
+# Cluster
+# -----------------------------------------------------------------------------
+
 cluster_mode = false
+
+# cluster_mode=true:
+# - requires MySQL or PostgreSQL
+# - local Tantivy cannot be used
+# - filesystem blob storage must be genuinely shared between all nodes,
+#   or S3-compatible storage must be used
+# - pgp_enabled must currently be false
+#
+# data_dir is not required as persistent node state when all required state
+# lives in SQL/shared blob storage/external search.
+
+
+# -----------------------------------------------------------------------------
+# Sessions
+# -----------------------------------------------------------------------------
+
+# database | redis
+session_backend = "database"
+
 session_timeout_hours = 72
+
 remember_me_enabled = true
 remember_me_days = 30
 
+# Required when sessions/database state must be decryptable by multiple nodes.
+# All RustBox nodes must use the same 32-byte base64-encoded key.
+#
+# session_encryption_key = "BASE64_32_BYTE_KEY"
+
+# Direct Redis:
+# redis_url = "redis://redis.example.com:6379/"
+
+# Redis Sentinel:
+# redis_sentinel_nodes = [
+#   "sentinel-a:26379",
+#   "sentinel-b:26379",
+#   "sentinel-c:26379",
+# ]
+# redis_sentinel_master = "mymaster"
+# redis_sentinel_password = "sentinel-secret"
+# redis_password = "secret"
+
+
+# -----------------------------------------------------------------------------
+# IMAP / SMTP
+# -----------------------------------------------------------------------------
+
 imap_host = "localhost"
 imap_port = 993
+
 smtp_host = "localhost"
 smtp_port = 587
+
 tls_enabled = true
+
+# Certificate and hostname verification.
+# Packaged default keeps the existing local-mail-server behavior.
 tls_verify = false
+
+# Maximum raw attachment size in MiB.
 max_attachment_size_mb = 50
+
+# Maximum complete RFC822/MIME message size in MiB.
 max_message_size_mb = 100
 
+
+# -----------------------------------------------------------------------------
+# ManageSieve
+# -----------------------------------------------------------------------------
+
+# If sieve_host is omitted, the IMAP host from the authenticated session
+# is used.
+#
+# sieve_host = "mail.example.com"
+
 sieve_port = 4190
+
+# starttls | implicit | none
 sieve_tls_mode = "none"
+
 sieve_allow_insecure_auth = true
 sieve_timeout_secs = 10
 
-default_junk_folder = "Spam"
+
-default_theme = "system"
+# -----------------------------------------------------------------------------
-default_interface_skin = "apple-mail"
+# Reverse proxy
+# -----------------------------------------------------------------------------
+
 trusted_proxies = "127.0.0.1,::1"
-outgoing_headers = []
+
+
+# -----------------------------------------------------------------------------
+# Special IMAP folders
+# -----------------------------------------------------------------------------
+
+# Optional server-wide defaults used when an account has no override
+# and the named folder exists.
+
+# default_sent_folder = "Sent"
+# default_drafts_folder = "Drafts"
+# default_trash_folder = "Trash"
+
+default_junk_folder = "Spam"
+
+# default_archive_folder = "Archive"
+
+
+# -----------------------------------------------------------------------------
+# Outgoing mail headers
+# -----------------------------------------------------------------------------
+
+# Additional headers added to every outgoing message.
+# Format: "Header-Name: value"
+#
+# Structural/MIME headers and CR/LF injection are rejected.
+#
+# Example:
+# outgoing_headers = [
+#   "X-Organization: Example Corp",
+# ]
+
+outgoing_headers = [
+    "X-Mailer: RustBox (https://git.linuxiarz.pl/gru/RustBox)",
+]
+
+
+# -----------------------------------------------------------------------------
+# OpenPGP
+# -----------------------------------------------------------------------------
 
 pgp_enabled = true
+
 pgp_wkd_enabled = true
+
 pgp_hkp_enabled = false
 pgp_hkp_url = "https://keys.openpgp.org"
+
 pgp_network_timeout_secs = 10
 pgp_max_key_bytes = 1048576
+
+# Packaged default preserves the existing package behavior.
 pgp_allow_private_export = true
 
-# Blob storage is independent from database_backend. This default preserves the
+# Current cluster deployments require:
-# single-node package behavior. PostgreSQL/MySQL may use this local filesystem
+#
-# backend too when cluster_mode=false.
+# pgp_enabled = false
+
+
+# -----------------------------------------------------------------------------
+# Blob storage
+# -----------------------------------------------------------------------------
+#
+# Blob storage is independent from database_backend.
+#
+# PostgreSQL/MySQL can use a local filesystem in single-node mode.
+#
+# Cluster deployments must use:
+# - S3-compatible object storage, or
+# - a genuinely shared POSIX filesystem such as NFS/CephFS/GlusterFS.
+#
+
 [storage]
+
+# filesystem | s3
 backend = "filesystem"
+
+# Filesystem backend.
 path = "/var/lib/rustbox/blobs"
+
+# Set true only when every RustBox node sees the same filesystem.
 shared = false
+
+# Optional object/key prefix.
+prefix = ""
+
 request_timeout_secs = 30
 connect_timeout_secs = 5
 max_retries = 3
 retry_timeout_secs = 60
 
-# Local Tantivy is single-node only. Cluster deployments must use opensearch or disabled.
+
+# --- S3-compatible backend ----------------------------------------------------
+#
+# Example:
+#
+# backend = "s3"
+#
+# bucket = "rustbox"
+# region = "eu-central-1"
+#
+# Custom endpoint for MinIO, SILO, Ceph RGW, OpenStack Swift s3api, etc.
+# AWS S3 normally does not require endpoint.
+#
+# endpoint = "https://s3.example.net"
+#
+# Enable for S3 implementations requiring path-style addressing.
+# path_style = false
+#
+# Explicitly allow an unencrypted HTTP endpoint.
+# Intended primarily for trusted development/internal networks.
+# allow_http = false
+#
+# Credentials may be configured here or through supported AWS environment
+# variables.
+#
+# access_key_id = "..."
+# secret_access_key = "..."
+#
+# Server-side encryption:
+#
+# server_side_encryption = "AES256"
+#
+# or:
+#
+# server_side_encryption = "aws:kms"
+# kms_key_id = "..."
+
+
+# -----------------------------------------------------------------------------
+# Search
+# -----------------------------------------------------------------------------
+#
+# Search is independent from both SQL and blob storage.
+#
+# local_tantivy:
+# - default packaged single-node backend
+# - cannot be used in cluster mode
+#
+# opensearch:
+# - recommended backend for cluster deployments
+#
+# disabled:
+# - completely disables search indexing
+#
+
 [search]
+
+# disabled | local_tantivy | opensearch
 backend = "local_tantivy"
+
+# Local Tantivy path.
 path = "/var/lib/rustbox/search"
+
+# OpenSearch endpoints:
+#
+# urls = [
+#   "https://opensearch.example.net:9200",
+# ]
+
 index_prefix = "rustbox"
+
+# If true, inability to use the configured search backend is treated
+# as a required-service failure.
 required = false
+
+# Permit plain HTTP OpenSearch endpoints.
+# Intended primarily for trusted development/internal networks.
+allow_insecure_http = false
+
 request_timeout_secs = 10
+
 worker_interval_secs = 2
 worker_batch_size = 100
 worker_max_attempts = 12
 
+# Optional OpenSearch HTTP authentication.
+#
+# username = "rustbox"
+# password = "change-me"
+
+
+# =============================================================================
+# CLUSTER EXAMPLES
+# =============================================================================
+#
+# Examples below are comments only. They do not affect the packaged defaults.
+
+
 # -----------------------------------------------------------------------------
-# Cluster example: PostgreSQL + S3-compatible storage + OpenSearch
+# PostgreSQL + S3-compatible storage + OpenSearch
 # -----------------------------------------------------------------------------
+#
 # database_backend = "pgsql"
 # database_url = "postgres://rustbox:change-me@db.internal/rustbox"
-# session_backend = "database" # or redis
+#
-# session_encryption_key = "BASE64_32_BYTE_KEY"
 # cluster_mode = true
+#
+# session_backend = "database"
+# session_encryption_key = "BASE64_32_BYTE_KEY"
+#
 # pgp_enabled = false
 #
 # [storage]
 # backend = "s3"
 # bucket = "rustbox"
 # region = "eu-central-1"
-# endpoint = "https://s3.example.net" # optional for AWS S3
+# endpoint = "https://s3.example.net"
 # path_style = false
 # allow_http = false
+# prefix = ""
 # request_timeout_secs = 30
 # connect_timeout_secs = 5
 # max_retries = 3
@@ -92,21 +368,58 @@ worker_max_attempts = 12
 # urls = ["https://opensearch.example.net:9200"]
 # index_prefix = "rustbox"
 # required = true
-# username = "rustbox"
+# allow_insecure_http = false
-# password = "change-me"
+# request_timeout_secs = 10
 # worker_interval_secs = 2
 # worker_batch_size = 100
 # worker_max_attempts = 12
-#
+# username = "rustbox"
-# In this shape data_dir is not required as persistent node state.
+# password = "change-me"
+
 
 # -----------------------------------------------------------------------------
-# Cluster blob alternative: shared POSIX/NFS/CephFS/GlusterFS
+# MySQL + shared NFS/CephFS/GlusterFS + OpenSearch
 # -----------------------------------------------------------------------------
+#
+# database_backend = "mysql"
+# database_url = "mysql://rustbox:change-me@db.internal/rustbox"
+#
+# cluster_mode = true
+#
+# session_backend = "database"
+# session_encryption_key = "BASE64_32_BYTE_KEY"
+#
+# pgp_enabled = false
+#
 # [storage]
 # backend = "filesystem"
 # path = "/mnt/rustbox-shared"
 # shared = true
+# prefix = ""
 #
-# `shared=true` is an operator assertion that every RustBox node sees the same
+# [search]
-# filesystem. It is not suitable for local Tantivy; use OpenSearch/disabled search.
+# backend = "opensearch"
+# urls = ["https://opensearch.example.net:9200"]
+# index_prefix = "rustbox"
+# required = true
+
+
+# -----------------------------------------------------------------------------
+# Cluster sessions using Redis
+# -----------------------------------------------------------------------------
+#
+# session_backend = "redis"
+# session_encryption_key = "BASE64_32_BYTE_KEY"
+#
+# redis_url = "redis://redis.internal:6379/"
+#
+# Or Sentinel:
+#
+# redis_sentinel_nodes = [
+#   "sentinel-a:26379",
+#   "sentinel-b:26379",
+#   "sentinel-c:26379",
+# ]
+# redis_sentinel_master = "mymaster"
+# redis_sentinel_password = "sentinel-secret"
+# redis_password = "secret"