Sambee 3.0

Configuration File Reference

This page is a compact map of the optional config.toml file.

Use config.example.toml as the source of truth for supported keys. This page explains the sections that matter most in day-to-day administration.

How to Use This Reference

  • Copy only the keys you actually need into the local config.toml.
  • Keep the file local to the deployment and mount it read-only in production.
  • Treat commented defaults in config.example.toml as the baseline behavior unless you override them intentionally.
  • Expect most basic deployments to use only a small subset of these keys.

High-Value Sections and Keys

SectionKeyOperational effect
[app]log_levelSets application diagnostic verbosity and Uvicorn lifecycle logging.
[app]access_log_levelSets Uvicorn HTTP request access-log verbosity.
[app]protocol_log_levelSets Uvicorn WebSocket connection, frame, and keepalive log verbosity.
[auth]disable_enforcementTemporarily bypasses all Sambee authentication enforcement at runtime.
[security]access_token_expire_minutesChanges the short-lived API-token lifetime. OIDC sessions refresh this token in the background; configure the OIDC interactive sign-in interval separately in Authentication settings.
[admin]usernameSets the initial administrator username.
[frontend_logging]logging_enabled, log_levelControls browser-console logging behavior.
[frontend_logging]tracing_enabled, tracing_level, tracing_retention_hoursControls backend trace collection for frontend logging.
[frontend_logging]tracing_components, tracing_username_regexRestricts tracing by component or user scope.
[directory_cache]locationSelects the private backend directory-index root. SQLite catalogues are reused after restart and marked unverified until background verification completes.
[preprocessors.imagemagick]max_file_size_bytes, timeout_secondsSets conversion limits for ImageMagick preprocessing.
[companion_downloads]metadata_feed_urlChanges where Sambee resolves Companion download metadata.
[companion_downloads.pin]version, published_at, notes, asset URLsPins Companion download links to a specific published release instead of following the promoted feed.

Image Conversion Preference

Use Settings > Administration > Image viewer > Image conversion preference to choose how backend image previews balance CPU use and transfer size. This setting also applies to libvips conversions. Local-drive images from Companion and original downloads are unchanged.

OptionBehavior
Conversion speed (default)Use JPEG for opaque previews. A JPEG that fits the requested dimensions is sent unchanged. Encoding uses less CPU, but files can be larger.
Target sizeUse WebP for opaque previews, including JPEGs that already fit. Keep the original fitting JPEG if WebP is not smaller. Conversion can use more CPU.

Images with an alpha band stay WebP in both modes, except ICO images with alpha, which use PNG. EPS and AI previews stay PNG.

The saved value applies to subsequent backend preview requests without a restart. Previously loaded gallery images can remain cached; reload the page to request them again.

This setting is stored as image_viewer.conversion_preference in the database, with speed or size as its value. There is no TOML or environment override. If the stored value is invalid, Sambee logs an error and uses the speed default. The public support report includes the effective value and its source.

Conversion Threshold

Image conversion threshold defaults to 5 MiB (5,242,880 bytes). Backend previews process browser-native images only when their known file size is strictly greater than this value. Zero processes every non-empty image. Formats that require conversion are always processed, regardless of this threshold. An unknown size keeps the existing format-based behavior.

This setting is stored only in the database as image_viewer.conversion_threshold_bytes. Changes apply to subsequent preview requests, including archive members, without a restart. Cached gallery images are not fetched again automatically. The old [image_viewer].conv_size_thresh configuration key is no longer supported and is not migrated.

The threshold is a transfer and conversion trade-off, not a decoded-pixel or memory limit. The 5 MiB default is a starting point, not a measured optimum. Compare 2, 5, and 10 MiB on the target device and network before tuning it. ImageMagick input-size and timeout limits are separate controls on the same page.

PDF compatibility and processing controls are under Administration > PDF viewer. Administration > System keeps archive creation limits. Personal and administration categories are each sorted by their translated labels.

File Search and History Policy

Use Settings > File Search for shared retention, results per group, and file-history exclusions. These are administrator settings, not personal File Browser preferences.

Recent files and directories to retain defaults to 200 files and 200 directories per user, with separate limits for the lists. Existing administrator overrides remain unchanged. Lowering retention immediately removes the oldest records from both lists; zero clears both lists and prevents new records. Results per group defaults to 10 and applies to both search modes.

Image, temporary, backup, and extension exclusions apply only to file history before storage. Enter one literal extension per exclusion; Sambee normalizes TMP to .tmp.

Users can clear their own histories in Settings > File Browser. Removing history does not delete stored files or folders.

Directory-Index Policy

Directory-index resource policies have no TOML override. Configure them in Admin > Directory Search; see Manage Directory Search for controls, Companion approval, and recovery.

directory_cache.location selects only the backend storage root.

Backend Logging Levels

The [app] logging keys accept DEBUG, INFO, WARNING, or ERROR, regardless of case.

[app]
log_level = "INFO"
access_log_level = "WARNING"
protocol_log_level = "WARNING"

log_level defaults to INFO. access_log_level and protocol_log_level default to WARNING, which keeps routine successful HTTP requests and verbose WebSocket frames or pings out of normal logs. Raise either setting only for focused diagnosis. Uvicorn startup, shutdown, and error messages continue to use log_level.

Keys That Deserve Extra Care

These areas have the highest operational impact:

  • [auth].disable_enforcement: Bypasses all Sambee authentication enforcement. Use it only with a trusted reverse proxy or network perimeter that already enforces access control. It does not change the mode selected in Authentication settings and requires a restart after removal. The retired auth_method key is rejected at startup.
  • Backend logging keys: Can significantly increase log volume, particularly protocol_log_level = "DEBUG".
  • Frontend logging and tracing keys: Can change both local debugging visibility and backend trace collection volume.
  • directory_cache.location: Changes where the saved SMB directory index lives on disk.
  • Companion download keys: Change what download links Sambee presents to users.