Skip to content

Configuration Reference

Jump to bottom
rustmailer edited this page Jan 20, 2026 · 2 revisions

Bichon Configuration Reference

Each setting can be specified as a command-line argument (--option-name) or via an environment variable (auto-detected by Bichon). Settings are grouped by functionality.

1. Logging & Output

Option CLI / Env Default Description
bichon_log_level --bichon-log-level / BICHON_LOG_LEVEL "info" Sets the log level for Bichon. Options: trace, debug, info, warn, error.
bichon_ansi_logs --bichon-ansi-logs / BICHON_ANSI_LOGS true Enable ANSI color formatting in logs.
bichon_log_to_file --bichon-log-to-file / BICHON_LOG_TO_FILE false Write logs to a file instead of stdout.
bichon_json_logs --bichon-json-logs / BICHON_JSON_LOGS false Enable JSON formatted logs.
bichon_max_server_log_files --bichon-max-server-log-files / BICHON_MAX_SERVER_LOG_FILES 5 Maximum number of server log files to retain.

2. Server & Network

Option CLI / Env Default Description
bichon_http_port --bichon-http-port / BICHON_HTTP_PORT 15630 Port for the HTTP server.
bichon_bind_ip --bichon-bind-ip / BICHON_BIND_IP "0.0.0.0" IPv4 address the server binds to (required in cluster mode). Must be valid IPv4.
bichon_public_url --bichon-public-url / BICHON_PUBLIC_URL "http://localhost:15630" Public URL for accessing Bichon.
bichon_cors_origins --bichon-cors-origins / BICHON_CORS_ORIGINS "http://localhost:5173, http://localhost:15630, *" Comma-separated list of allowed CORS origins. * allows all.
bichon_cors_max_age --bichon-cors-max-age / BICHON_CORS_MAX_AGE 86400 Maximum age in seconds for CORS preflight cache.
bichon_enable_access_token --bichon-enable-access-token / BICHON_ENABLE_ACCESS_TOKEN false Enable HTTP access token validation.
bichon_enable_rest_https --bichon-enable-rest-https / BICHON_ENABLE_REST_HTTPS false Enable HTTPS for REST API endpoints.

3. Database & Storage

Option CLI / Env Default Description
bichon_root_dir --bichon-root-dir / BICHON_ROOT_DIR none Absolute path for Bichon core data. Contains encrypted account info.
bichon_index_dir --bichon-index-dir / BICHON_INDEX_DIR ${bichon_root_dir}/envelope Path for the metadata Tantivy index. Stores envelopes and server sync info.
bichon_data_dir --bichon-data-dir / BICHON_DATA_DIR ${bichon_root_dir}/eml Path for the data Tantivy index. Stores raw email content (unencrypted).
bichon_metadata_cache_size --bichon-metadata-cache-size / BICHON_METADATA_CACHE_SIZE 134_217_728 Cache size (bytes) for metadata database.
bichon_envelope_cache_size --bichon-envelope-cache-size / BICHON_ENVELOPE_CACHE_SIZE 1_073_741_824 Cache size (bytes) for envelope database.
bichon_encrypt_password --bichon-encrypt-password / BICHON_ENCRYPT_PASSWORD "change-this-default-password-now" Encryption password for core database/files. ⚠️ Change in production.

Storage Customization (v0.3.2+)

Starting from version 0.3.2, you can decouple the search index and data storage from the root directory. This is useful for moving large datasets to different drives.

  • BICHON_INDEX_DIR (Metadata Index): A standalone Tantivy index instance. It stores metadata extracted from emails and other information retrieved from mail servers.
  • BICHON_DATA_DIR (Data Index): A standalone Tantivy index instance. It contains the primary email message data. While it functions as an index, you can think of it as the storage for your entire collection of emails.

Migration & Backup:

  • Migration: You can manually move the existing envelope and eml directories from your root folder to new locations, then update these parameters accordingly. Renaming the directories after moving is also supported.
  • Security: These two directories are not encrypted. They are designed for high-performance indexing and search.
  • Backup: A complete backup requires all three locations: bichon_root_dir (encrypted settings), bichon_index_dir (metadata), and bichon_data_dir (email content).

4. Email Synchronization

Option CLI / Env Default Description
bichon_sync_concurrency --bichon-sync-concurrency / BICHON_SYNC_CONCURRENCY #CPU cores × 2 Maximum number of concurrent email sync tasks. Must be ≥ 1.

5. HTTP / API Features

Option CLI / Env Default Description
bichon_http_compression_enabled --bichon-http-compression-enabled / BICHON_HTTP_COMPRESSION_ENABLED true Enable HTTP compression for API responses.

6. Compression Algorithm (Optional Enum)

Algorithm CLI Value Description
None none No compression.
Gzip gzip Use Gzip compression.
Brotli brotli Use Brotli compression.
Zstd zstd Use Zstandard compression.
Deflate deflate Use Deflate compression.

Usage Notes

  1. Command-line arguments take precedence over environment variables:
bichon --bichon-log-level debug --bichon-http-port 8080
  1. **Environment variables can be used to configure without CLI arguments:
export BICHON_LOG_LEVEL=debug
export BICHON_HTTP_PORT=8080

Clone this wiki locally