設定

すべての設定は環境変数を通じて行います。各変数には妥当なデフォルト値があるため、SnapOtter は何も設定しなくてもそのまま動作します。

環境変数

サーバー

変数	デフォルト	説明
PORT	1349	サーバーがリッスンするポート。
RATE_LIMIT_PER_MIN	1000	IP ごとの 1 分あたりの最大リクエスト数。レート制限を無効にするには 0 に設定します。
CORS_ORIGIN	(空)	CORS で許可するオリジンのカンマ区切りリスト。空の場合は同一オリジンのみ。
LOG_LEVEL	info	ログの詳細度。fatal、error、warn、info、debug、trace のいずれか。
TRUST_PROXY	loopback,linklocal,uniquelocal	X-Forwarded-For でクライアント IP を設定できるピアを指定します。デフォルトはプライベートネットワークのピアだけを信じるため、Docker ネットワークや LAN 上のリバースプロキシは信頼され、公開クライアントが偽装したヘッダーは信頼されません。公開アドレスで自分が管理するプロキシを前段に置いている場合にのみ true に設定してください。

認証

以下の 2 つのブール値は true と false のみを受け付けます。1、yes、on などそれ以外の値は検証に失敗し、サーバーはリッスンを開始する前に終了します。

変数	デフォルト	説明
AUTH_ENABLED	true	ログインを必須にします。アカウントをまったく持たずに実行するには false に設定します。その場合はすべてのリクエストに admin 権限が与えられるため、信頼できるネットワークに限定してください。
DEFAULT_USERNAME	admin	初期 admin アカウントのユーザー名。初回起動時のみ使用されます。
DEFAULT_PASSWORD	admin	初期 admin アカウントのパスワード。初回ログイン後に変更してください。
MAX_USERS	0 (無制限)	登録済みユーザーアカウントの最大数。無制限にするには 0 に設定します。
SESSION_DURATION_HOURS	168	ログインセッションの有効期間（時間単位、デフォルトは 7 日）。
SKIP_MUST_CHANGE_PASSWORD	false	初回ログイン時の強制パスワード変更プロンプトをスキップするには true に設定します。

ストレージ

変数	デフォルト	説明
STORAGE_MODE	local	local または s3。S3 と MinIO には s3_storage 機能を含むライセンスに加えて、以下の S3_* 変数が必要です。
DATABASE_URL	postgres://snapotter:snapotter@localhost:5432/snapotter	PostgreSQL 接続文字列。Compose スタックではこれを自身の postgres サービスに向けます。組み込みモードにするには、（REDIS_URL と併せて）未設定のままにします。
REDIS_URL	redis://localhost:6379	Redis 接続文字列（BullMQ ジョブキューに使用）。Compose ではこれを自身の redis サービスに向けます。
WORKSPACE_PATH	./tmp/workspace	処理中の一時ファイル用ディレクトリ。自動的にクリーンアップされます。イメージでは /tmp/workspace が設定されます。
FILES_STORAGE_PATH	./data/files	永続的なユーザーファイル（アップロードした画像、保存した結果）用ディレクトリ。イメージでは /data/files が設定されます。

S3 オブジェクトストレージ

STORAGE_MODE=s3 のときにのみ読み取られます。必須の 3 つのうちどれか 1 つでも欠けていると起動は失敗し、設定し忘れた変数名が表示されます。

変数	デフォルト	説明
S3_BUCKET	(空)	アップロードと出力を保持するバケット。必須。
S3_ACCESS_KEY_ID	(空)	アクセスキー。必須。コンテナ内では、代わりに S3_ACCESS_KEY_ID_FILE でマウントすることもできます。
S3_SECRET_ACCESS_KEY	(空)	シークレットキー。必須。同じファイル方式が使えます: S3_SECRET_ACCESS_KEY_FILE。
S3_REGION	us-east-1	バケットのリージョン。
S3_ENDPOINT	(空)	MinIO、R2、Backblaze など S3 互換ストア向けのカスタムエンドポイント。空の場合は AWS を指します。
S3_FORCE_PATH_STYLE	false	MinIO のように、仮想ホスト形式ではなく endpoint/bucket/key を必要とするものでは true に設定します。
S3_PREFIX	(空)	キーのプレフィックス。1 つのバケットで複数のインスタンスを扱えるようになります。

保存データの暗号化

変数	デフォルト	説明
DATA_ENCRYPTION_KEY	(空)	64 文字の 16 進数（32 バイト）。データベースに保存された機密設定を暗号化します。64 文字の 16 進数でないものは起動時に拒否されます。
DATA_ENCRYPTION_KEY_PREVIOUS	(空)	ローテーションで置き換える前のキー。形式は同じです。ローテーション中は両方を設定して既存の行を復号できるようにし、その後こちらを削除します。

組み込みモード

DATABASE_URL も REDIS_URL も指定せずにイメージを実行すると、コンテナ内で独自の PostgreSQL 17 と Redis を起動し、ループバックにバインドして、すべてのデータを /data ボリューム上に置きます。これにより、クイックスタート、ホームラボ、1.x からのアップグレード向けに、ワンコマンドの docker run 体験が復活します。これは利便性のための手段であり、本番デプロイではありません。本番環境では、PostgreSQL と Redis を分離した 3 コンテナの Compose スタックを実行してください。組み込みモードはコンテナを root として実行する必要があり、任意 UID のランタイム（OpenShift、Kubernetes runAsNonRoot）とは互換性がありません。その場合は Compose を使用してください。

変数	デフォルト	説明
EMBEDDED	auto	DATABASE_URL と REDIS_URL の両方が未設定の場合に自動で有効になります。無効にするには 0 に設定します（その場合、外部の DATABASE_URL/REDIS_URL が設定されていなければ、アプリはコンテナ内データベースを黙って起動する代わりに即座に失敗します）。
REDIS_MAXMEMORY	512mb	組み込み Redis のメモリ上限（組み込みモードのみ）。Raspberry Pi のようなメモリ制約のあるホストでは下げてください。

1.x からのアップグレード: 古い snapotter.db をボリューム内の /data/snapotter.db に配置すると、組み込みモードが初回起動時にそれを組み込み PostgreSQL へインポートします。インポートは一度だけ実行され、以降の起動ではスキップされます。

テレメトリに関する注記: 組み込みモードは、他の設定と同様にイメージの分析デフォルトを継承します。公開イメージは分析を有効にした状態で出荷されます。無効にするには --build-arg SNAPOTTER_ANALYTICS=off でビルドするか、アプリ内の admin オプトアウトを使用してください。

処理制限

変数	デフォルト	説明
MAX_UPLOAD_SIZE_MB	0 (無制限)	アップロードあたりの最大ファイルサイズ（メガバイト単位）。無制限にするには 0 に設定します。公開イメージは 0 で出荷されます。ソースからのビルドは 100 で始まります。
MAX_BATCH_SIZE	0 (無制限)	単一バッチリクエスト内の最大ファイル数。無制限にするには 0 に設定します。公開イメージは 0 で出荷されます。ソースからのビルドは 100 で始まります。
CONCURRENT_JOBS	0 (自動)	並列実行されるバッチジョブの数。利用可能な CPU コア数に基づいて自動検出するには 0 に設定します。
MAX_MEGAPIXELS	0 (無制限)	許可される最大画像解像度（メガピクセル単位）。無制限にするには 0 に設定します。
MAX_WORKER_THREADS	0 (自動)	画像処理の最大ワーカースレッド数。利用可能な CPU コア数に基づいて自動検出するには 0 に設定します。
PROCESSING_TIMEOUT_S	0 (制限なし)	リクエストあたりの最大処理時間（秒単位）。タイムアウトなしにするには 0 に設定します。
MAX_PIPELINE_STEPS	20	パイプライン内の最大ステップ数。制限なしにするには 0 に設定します。
MAX_CANVAS_PIXELS	0 (制限なし)	出力画像の最大キャンバスサイズ（ピクセル単位）。制限なしにするには 0 に設定します。
MAX_SVG_SIZE_MB	50	サニタイズ前に受け付ける SVG の最大サイズ（メガバイト単位）。ここでの 0 は前後の行とは動作が異なります。上限を引き上げるのではなく、解析前のサイズ上限そのものを取り除くため、この項目は設定したままにしてください。
MAX_PDF_PAGES	0 (無制限)	PDF-to-image 変換での PDF の最大ページ数。無制限にするには 0 に設定します。

クリーンアップ

変数	デフォルト	説明
FILE_MAX_AGE_HOURS	72	未保存の処理結果（生のアップロードとツール出力）を自動削除するまで保持する期間。Files ライブラリに明示的に保存したファイルは影響を受けず、削除するまで保持されます。
CLEANUP_INTERVAL_MINUTES	60	クリーンアップジョブを実行する頻度。

外観

変数	デフォルト	説明
DEFAULT_THEME	light	新規セッションのデフォルトテーマ。light、dark、system のいずれか。
DEFAULT_LOCALE	en	デフォルトのインターフェース言語。
DEFAULT_TOOL_VIEW	sidebar	デフォルトのツールレイアウト。sidebar または fullscreen。

Docker 権限

変数	デフォルト	説明
PUID	999	コンテナプロセスをこの UID として実行します。バインドマウントの場合はホストユーザーに合わせて設定します（id -u）。
PGID	999	コンテナプロセスをこの GID として実行します。バインドマウントの場合はホストグループに合わせて設定します（id -g）。

Docker の例

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
      - DATABASE_URL=postgres://snapotter:snapotter@postgres:5432/snapotter
      - REDIS_URL=redis://redis:6379
      - MAX_UPLOAD_SIZE_MB=200
      - CONCURRENT_JOBS=4
      - FILE_MAX_AGE_HOURS=12
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: snapotter
      POSTGRES_PASSWORD: snapotter     # 非ローカル展開の場合はこれを変更します
      POSTGRES_DB: snapotter
    volumes:
      - SnapOtter-pgdata:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U snapotter -d snapotter"]
      interval: 10s
      timeout: 5s
      retries: 12

  redis:
    image: redis:8-alpine
    command: ["redis-server", "--maxmemory-policy", "noeviction", "--appendonly", "yes"]
    volumes:
      - SnapOtter-redisdata:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 12

volumes:
  SnapOtter-data:
  SnapOtter-workspace:
  SnapOtter-pgdata:
  SnapOtter-redisdata:

ボリューム

Docker Compose スタックは 4 つのボリュームを使用します:

• /data (app) - AI モデル、Python venv、ユーザーファイル。アップロードしたファイルとインストール済みの AI バンドルを再起動を越えて保持するには、これをマウントします。
• /tmp/workspace (app) - 処理中のファイルの一時ストレージ。エフェメラルでも構いませんが、マウントするとコンテナの書き込み可能レイヤーが埋まるのを防げます。
• SnapOtter-pgdata (postgres) - PostgreSQL データディレクトリ。すべてのリレーショナルデータ（ユーザー、設定、パイプライン、ジョブ、監査ログ）を保持します。pg_dump またはボリュームスナップショットでバックアップします。
• SnapOtter-redisdata (redis) - 永続的なジョブキュー用の Redis 追記専用ファイル。