SnapOtter/apps/docs/guide/configuration.md

description

description
All SnapOtter environment variables with defaults. Configure auth, storage, AI models, analytics, and more.

Configuration

All configuration is done through environment variables. Every variable has a sensible default, so SnapOtter works out of the box without setting any of them.

Environment variables

Server

Variable	Default	Description
PORT	1349	Port the server listens on.
RATE_LIMIT_PER_MIN	0 (disabled)	Maximum requests per minute per IP. Set to 0 to disable rate limiting.
CORS_ORIGIN	(empty)	Comma-separated allowed origins for CORS, or empty for same-origin only.
LOG_LEVEL	info	Log verbosity. One of: fatal, error, warn, info, debug, trace.
TRUST_PROXY	true	Trust X-Forwarded-For headers from a reverse proxy. Set to false if not behind a proxy.

Authentication

Variable	Default	Description
AUTH_ENABLED	false	Set to true to require login. The Docker image defaults to true.
DEFAULT_USERNAME	admin	Username for the initial admin account. Only used on first run.
DEFAULT_PASSWORD	admin	Password for the initial admin account. Change this after first login.
MAX_USERS	0 (unlimited)	Maximum number of registered user accounts. Set to 0 for unlimited.
SESSION_DURATION_HOURS	168	Login session lifetime in hours (default is 7 days).
SKIP_MUST_CHANGE_PASSWORD	-	Set to any non-empty value to bypass the forced password-change prompt on first login

Storage

Variable	Default	Description
STORAGE_MODE	local	local or s3. Only local storage is currently implemented.
DB_PATH	./data/snapotter.db	Path to the SQLite database file.
WORKSPACE_PATH	./tmp/workspace	Directory for temporary files during processing. Cleaned up automatically.
FILES_STORAGE_PATH	./data/files	Directory for persistent user files (uploaded images, saved results).

Processing limits

Variable	Default	Description
MAX_UPLOAD_SIZE_MB	0 (unlimited)	Maximum file size per upload in megabytes. Set to 0 for unlimited.
MAX_BATCH_SIZE	0 (unlimited)	Maximum number of files in a single batch request. Set to 0 for unlimited.
CONCURRENT_JOBS	0 (auto)	Number of batch jobs that run in parallel. Set to 0 to auto-detect based on available CPU cores.
MAX_MEGAPIXELS	0 (unlimited)	Maximum image resolution allowed in megapixels. Set to 0 for unlimited.
MAX_WORKER_THREADS	0 (auto)	Maximum worker threads for image processing. Set to 0 to auto-detect based on available CPU cores.
PROCESSING_TIMEOUT_S	0 (no limit)	Maximum processing time per request in seconds. Set to 0 for no timeout.
MAX_PIPELINE_STEPS	0 (no limit)	Maximum number of steps in a pipeline. Set to 0 for no limit.
MAX_CANVAS_PIXELS	0 (no limit)	Maximum canvas size in pixels for output images. Set to 0 for no limit.
MAX_SVG_SIZE_MB	0 (unlimited)	Maximum SVG file size in megabytes. Set to 0 for unlimited.
MAX_SPLIT_GRID	100	Maximum grid dimension for the image split tool.
MAX_PDF_PAGES	0 (unlimited)	Maximum number of PDF pages for PDF-to-image conversion. Set to 0 for unlimited.

Cleanup

Variable	Default	Description
FILE_MAX_AGE_HOURS	72	How long temporary files are kept before automatic deletion.
CLEANUP_INTERVAL_MINUTES	60	How often the cleanup job runs.

Appearance

Variable	Default	Description
DEFAULT_THEME	light	Default theme for new sessions. light or dark.
DEFAULT_LOCALE	en	Default interface language.
DEFAULT_TOOL_VIEW	sidebar	Default tool layout. sidebar or fullscreen.

Docker permissions

Variable	Default	Description
PUID	999	Run the container process as this UID. Set to match your host user for bind mounts (id -u).
PGID	999	Run the container process as this GID. Set to match your host group for bind mounts (id -g).

Docker example

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    ports:
      - "1349:1349"
    volumes:
      - SnapOtter-data:/data
      - SnapOtter-workspace:/tmp/workspace
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD=changeme
      - MAX_UPLOAD_SIZE_MB=200
      - CONCURRENT_JOBS=4
      - FILE_MAX_AGE_HOURS=12
    restart: unless-stopped

Volumes

The Docker container uses two volumes:

• /data -- Persistent storage for the SQLite database and user files. Mount this to keep users, API keys, saved pipelines, and uploaded images across container restarts.
• /tmp/workspace -- Temporary storage for images being processed. This can be ephemeral, but mounting it avoids filling up the container's writable layer.