Configuration reference

This file contains all available configuration options for the Gallery application.
Copy this configuration to your gallery.toml file and modify the values as needed.

Server Configuration#

[Server]
# Port on which the Gallery server will listen
# Default: 8080
Port = 8080

# Enable secure cookie flag (HTTPS only)
# Set to false if running behind HTTP reverse proxy that handles HTTPS
# Default: true
SecureCookie = true

# Session duration in minutes
# How long user sessions remain valid before requiring re-authentication
# Default: 480 (8 hours)
sessionDuration = 480

# HTTP server timeout settings for DoS protection
# ReadTimeout: Maximum time to read the entire request including headers and body
# Prevents slowloris attacks where clients send data very slowly
# Default: 30 seconds
readTimeout = 30

# WriteTimeout: Maximum time to write the response to the client
# Prevents slow response attacks and connection hanging
# Default: 30 seconds  
writeTimeout = 30

# IdleTimeout: Maximum time to wait for the next request on keep-alive connections
# Prevents connection exhaustion by closing idle connections
# Default: 120 seconds (2 minutes)
idleTimeout = 120

# Maximum file upload size in megabytes (MB)
# Controls the maximum size for all file uploads (photos, videos, thumbnails, profile photos)
# Larger values allow bigger uploads but consume more memory and storage
# Default: 10 MB
maxUploadSize = 10

Logging Configuration#

[Logging]
# Enable JSON structured logging
# When true, logs are output in JSON format for better parsing by log management systems
# When false, logs are output in human-readable plain text format
# Default: true
Json = true

# Enable debug logging
# When true, includes detailed debug information in logs
# Useful for troubleshooting but can create very large log files
# Default: false
Debug = false

Database Configuration#

[Database]
# Database type to use
# Currently supported: "SQLite"
# Future versions may support PostgreSQL, MySQL, etc.
# Default: "SQLite"
Type = "SQLite"

[Database.SQLite]
# Path to the SQLite database file
# Can be absolute or relative path
# Default: "/config/gallery/gallery.db"
Path = "/config/gallery/gallery.db"

Data Storage Configuration#

[Data]
# Base path for all Gallery data storage
# This directory will contain all uploaded files, thumbnails, and database files
# Should be on a disk with sufficient storage space
# Default: "/config/gallery/"
BasePath = "/config/gallery/"

Rate Limiting Configuration#

Controls how many requests can be made within specific time periods to prevent abuse.

[RateLimit]

[RateLimit.Auth]
# Rate limits for authentication endpoints (login, register, etc.)
# More restrictive to prevent brute force attacks
requestsPerMinute = 5   # Max login attempts per minute
requestsPerHour = 20    # Max login attempts per hour  
requestsPerDay = 100    # Max login attempts per day

[RateLimit.Default]
# Rate limits for regular API endpoints
# Balanced to allow normal usage while preventing abuse
requestsPerMinute = 60   # Max requests per minute
requestsPerHour = 1000   # Max requests per hour
requestsPerDay = 10000   # Max requests per day

[RateLimit.FileUpload]
# Rate limits for file upload endpoints
# More restrictive due to resource consumption
requestsPerMinute = 10   # Max uploads per minute
requestsPerHour = 100    # Max uploads per hour
requestsPerDay = 500     # Max uploads per day

Authentication Configuration#

[Auth]
# Authentication methods to enable
# At least one method must be enabled
# Default: UseSimple = true, UseSSO = false
UseSSO = false    # Enable SSO/OIDC authentication
UseSimple = true  # Enable simple username/password authentication

# Simple authentication configuration
[Auth.Simple]
# JWT secret for token signing
# Should be a long, random string
# Auto-generated on first run if not specified
# IMPORTANT: Change this in production environments!
JWTSecret = "your-super-secret-jwt-key-here"

# SSO/OIDC authentication configuration  
[Auth.SSO]
# OIDC provider configuration
# Required when UseSSO = true
ClientID = "your-oidc-client-id"
ClientSecret = "your-oidc-client-secret" 
RedirectURL = "http://localhost:8080/auth/callback"
IssuerURL = "https://your-oidc-provider.com"

CSRF Protection Configuration#

[CSRF]
# Enable CSRF protection
# Prevents Cross-Site Request Forgery attacks
# Recommended to keep enabled in production
# Default: true
Enabled = true

# CSRF enforcement mode
# "strict" - Strict validation, rejects requests without valid tokens
# "permissive" - Allows some requests without tokens for development
# "disabled" - Disables CSRF protection (not recommended for production)
# Default: "strict"
EnforcementMode = "strict"

# CSRF token expiration time in minutes
# How long CSRF tokens remain valid
# Should match or be less than session duration
# Default: 480 (8 hours)
TokenExpiryMinutes = 480

# CSRF cookie SameSite attribute
# "Strict" - Cookie not sent on cross-site requests (most secure)
# "Lax" - Cookie sent on safe cross-site requests (good for OIDC)
# "None" - Cookie always sent (requires Secure flag)
# Default: "Lax" for OIDC compatibility
SameSiteMode = "Lax"

Transcoding Configuration#

[Transcode]
# Hardware acceleration for video transcoding
# Available options:
# "cpu" - Software encoding (compatible but slower)
# "nvidia" - NVIDIA GPU encoding (requires NVIDIA GPU)
# "amd" - AMD GPU encoding (requires AMD GPU)  
# "intel" - Intel GPU encoding (requires Intel GPU)
# "metal" - Apple Metal encoding (macOS only)
# "auto" - Automatically detect best available hardware
# Default: "cpu"
Transcode = "cpu"

# JWT expiration time for transcoding jobs in minutes
# How long transcoding job tokens remain valid
# Set to 0 or negative for tokens that never expire
# Default: 720 (12 hours)
JWTExpiration = 720

Offline download retention, concurrency, and the disk cap are set in Admin → Config → Transcode, not in the TOML file. See offlineDownloads.md.

Password Policy Configuration#

[Config.PasswordPolicy]
# Password requirements for user accounts
# Enforces strong passwords to improve security

# Minimum password length
# Default: 3 characters
MinLength = 3

# Maximum password length  
# Default: 101 characters
MaxLength = 101

# Require uppercase letters (A-Z)
# Default: true
RequireUpper = true

# Require lowercase letters (a-z)
# Default: true  
RequireLower = true

# Require numbers (0-9)
# Default: true
RequireNumber = true

# Require special characters (!@#$%^&* etc.)
# Default: true
RequireSpecial = true

Map Configuration#

[Map.OpenStreetMap]
# OpenStreetMap integration for photo location display
# Shows maps with photo location metadata when available

# Enable map display
# Default: true
Enabled = true

# OpenStreetMap tile server URL
# Uses {z}, {x}, {y} placeholders for zoom level and coordinates
# Default: "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
TileServer = "https://tile.openstreetmap.org/{z}/{x}/{y}.png"

Smart Search#

Smart search finds photos and videos by what they show (“red car”, “kids on a swing at dusk”). It runs a CLIP model in the server process with ONNX Runtime. It is off by default: an owner turns on the smart_search feature flag in Admin → Features.

[SmartSearch]
# Path of the ONNX Runtime shared library.
# Empty uses the GALLERY_ONNXRUNTIME_LIB environment variable, then
# /opt/onnxruntime/lib/libonnxruntime.so, where the release image installs it.
# Set it only for a custom install, e.g. a build that runs outside the image.
# Default: ""
onnxRuntimeLibrary = ""

If the library does not load, smart search requests fail and Admin → Smart Search shows the load error. The rest of the server keeps running. Face recognition uses the same library and the same setting.

Model files. Gallery downloads the model on first use into <BasePath>/data/models/<model_id>/ and checks each file’s SHA256 hash. The default model (ViT-B/32) is about 610 MB; the low-memory model (ViT-B/32 int8) is about 155 MB. A file put there by hand with the right hash is used as is, so an offline server can be prepared in advance.

Built-in models. Both built-in models are OpenAI’s CLIP ViT-B/32 weights (MIT license), downloaded from the MIT-licensed Xenova/clip-vit-base-patch32 repository at a pinned commit.

Custom models. In Admin → Smart Search → Custom models, an owner can add another model from their own URLs, for example a mirror on their own network or a different CLIP model. Gallery does not check the license of a custom model: the owner who adds it must have the right to use it.

• The model must be a CLIP-style ONNX export: an image encoder with one [1, 3, size, size] float input, a text encoder with one [1, contextLength] token input, and a CLIP BPE tokenizer.json (OpenAI CLIP and OpenCLIP/LAION exports work; SigLIP does not yet).
• Image size (default 224), context length (default 77), and the RGB mean and std (default: the OpenAI CLIP values) are set per model.
• A SHA256 per file is optional. Without one, Gallery accepts the file of the first download, stores its SHA256 and size, and rejects any different file later. A file without a known size is limited to 4 GB.
• Nothing downloads until the model is selected and vectors are generated. The files go to <BasePath>/data/models/custom-<id>/.
• Only the name and description can change later, because stored vectors depend on the files. To use other files, delete the model and add it again. A selected model cannot be deleted. Deleting a model also deletes its files and vectors.

Admin settings. These are stored in the database, not in this file. Change them in Admin → Smart Search (owners only):

Setting	Default	Notes
Model	ViT-B/32	A built-in or custom model. A different model needs a re-index; the panel offers one.
Cache budget	512 MB	Memory for search vectors. About 0.65 KB per vector, so ~800k vectors.
Threads	0 (half the CPUs)	ONNX Runtime threads per encoder.
Image encoder idle	5 minutes	Unload time after the last indexing job.
Text encoder idle	15 minutes	Unload time after the last search.
Video frames	8	Frames sampled per video, one per 30 s. API only. Run “Regenerate all” after a change.
Minimum score	0.20	Results below it are dropped. API only.

Memory (measured): the default model uses up to about 600 MB while indexing and about 400 MB for search. Each encoder unloads when idle. The int8 model uses about 170 MB for both.

Face Recognition#

Face recognition (people) is off by default. An owner turns on the face_recognition feature flag in Admin → Features. It has no settings in this file, except the ONNX Runtime library path of the Smart Search section. Its models, thresholds, and custom models are admin settings stored in the database.

Face vectors are biometric data. See Face Recognition for the privacy notes, how to delete all face data, the custom model license notice, and how to add the better SCRFD + ArcFace models.

AI Accounts#

AI features (photo title, description, and tag suggestions) are not configured in the TOML file. Each user adds their own AI accounts under Settings → AI Accounts while the ai_accounts feature flag (beta, off by default) is enabled.

• Anyone can add accounts for hosted providers with fixed URLs: OpenAI, Anthropic, Google Gemini, Mistral, Groq, OpenRouter, and xAI.
• Only server owners can add accounts that point at a custom URL: Ollama, LM Studio, or any OpenAI-compatible server. An owner can share such an account with other users or groups.
• Owners and admins can make an account they manage system-wide, so every user can use it. Owners and admins can see and edit every account in the admin panel, but never its API key.

API keys are encrypted with Config.AIAccountEncryptionKey, which is generated into the config file on first start.

TMDB Configuration#

[TMDB]
# The Movie Database (TMDB) API integration
# Used for movie/TV show metadata and poster fetching
# Required for video transcoding and cinematic features

# TMDB API key
# Required for video metadata fetching
# Get from https://www.themoviedb.org/settings/api
# Default: "" (must be specified for video features)
ApiKey = "your-tmdb-api-key-here"

Internal Configuration (Auto-Generated)#

The following settings are automatically managed by Gallery and should not be manually modified:

[Config]
# Gallery configuration directory (auto-generated)
# Do not modify this setting
GalleryConfigDirectory = "/config/gallery"

# Magic share link encryption key (auto-generated)
# Used to encrypt secure share links
# Automatically generated on first run if not specified
MagicShareLinkEncryptionKey = "auto-generated-encryption-key"

Configuration Tips#

1. Security: Always change the JWTSecret in production environments
2. Performance: Adjust rate limits based on your server capacity
3. Storage: Ensure sufficient disk space for your configured upload limits
4. Network: Configure timeouts based on your network conditions
5. Monitoring: Enable debug logging temporarily for troubleshooting
6. Backups: Regularly backup your configuration and database

Environment Variables#

Gallery supports environment variable overrides for all configuration settings.
Use the format GALLERY_SECTION_SETTING (e.g., GALLERY_SERVER_PORT=8080).

Example:

export GALLERY_SERVER_PORT=9000
export GALLERY_DATABASE_SQLITE_PATH="/custom/path/gallery.db"
export GALLERY_LOGGING_DEBUG=true

Configuration Validation#

Gallery automatically validates configuration on startup and will:

• Generate missing required settings with secure defaults
• Warn about potentially insecure or suboptimal settings
• Reject invalid configuration values and exit with error
• Log the final configuration for verification