#Configuration

HomeGallery has serveral modules/parts which can be configured through the gallery.config.yml file. It is loaded on the start of the CLI and is created if not found. It comes with a well selected preset of settings.

In a bare minimum configuration you need to define your media directories:

sources:
  - ~/Pictures

By default the configuration files are stored to ~/.config/home-gallery and the previews are stored in ~/.cache/home-gallery/storage.

It is advisable to initialize the configuration through the run init command:

gallery run init --source ~/Pictures /mnt/media

#Full configuration

The full configuration contains valuable details to some settings

# yaml-language-server: $schema=https://raw.githubusercontent.com/xemle/home-gallery/master/gallery.config.schema.json
#
# HomeGallery configuration file
#
# Default configuration file is gallery.config.yml.
# JSON format is also supported (gallery.config.json)
#
# Directory value examples:
# - /absolute/directory
# - relative/directory/to/current/working/dir
# - ~/directory/in/your/home
# - ./relative/directory/to/configuration/file
#
# Variable replacement example:
#
#   baseDir: '~'
#   configDir: '{baseDir}/.config/home-gallery'
#
# configDir is replaced to '~/.config/home-gallery' and than to '$HOME/.config/home-gallery'
#
# Variables are overwritten by environment variables
#
# Variables are baseDir, configDir, configPrefix, cacheDir and dir in sources
# or environment variables GALLERY_BASE_DIR, GALLERY_CONFIG_DIR, GALLERY_CONFIG_PREFIX, GALLERY_CACHE_DIR
#


# Base directory
#
# default: ~
#baseDir: ~
# default: '{baseDir}/.config/home-gallery'
#configDir: '{baseDir}/.config/home-gallery'
# file prefix for index, database and events
#
# default: ''
#configPrefix: ''
# Cache directory for storage directory and other cache files
#
# default: '{baseDir}/.cache/home-gallery'
#cacheDir: '{baseDir}/.cache/home-gallery'

#
# Sources
#
# List of media source directories. These can be read only.
#
# All sources are used to build the gallery database. If you need
# different databases or gallery instances use different gallery
# configurations
#
# default: []
#
#sources:
  # Simple source directory with default settings
  #- /home/me/Photos
  # Source directory with custom settings
  # [dir property] Path of source directory
  #- dir: /home/me/Photos
    # Index filename which must be unique
    #
    # For directory /mnt/photos the index file is {configDir}/photos.idx
    # If two sources have the same index file an error is raised
    #
    # default: '{configDir}/{configPrefix}{basename(dir)}.idx'
    #index: '{configDir}/{configPrefix}{basename(dir)}.idx'
    #
    # All files and subdirectories are included by default.
    # Set exclude patterns to ignore some files or foldes.
    # Last match wins
    #
    # Exclude patterns are using gitignore patterns (see https://git-scm.com/docs/gitignore)
    #
    # To include only one subdirectory you need to use:
    # - **       # exclude/ignores everything
    # - !/dir    # include dir name
    # - !/dir/** # include everything below /dir
    #
    #excludes:
      # examples:
      #   * '.DS_Store'
      #   * '._*'
      #   * "'*.tmp'"
      #   * "'*cache*'"
      #- '.DS_Store'
    # Read exclude patterns from file (one pattern per line)
    #excludeFromFile: '{configDir}/excludes'
    # If a file with this name is present in a directory, the this directory is excluded
    #
    # default: '.galleryignore'
    #excludeIfPresent: '.galleryignore'
    # Exclude big files such as videos to speedup initial setup
    #
    # examples:
    #   * '20M'
    #   * '1G'
    #maxFileSize: '20M'
    # If source directory/disk is offline/unmounted set it to true.
    # Offline sources require an index file. Previews and meta data
    # should be extracted first before marking a source offline
    #offline: true
    # Allows the original files to be downloaded via de webapp.
    # This adds a link to images of this source in the details view.
    # Sources set as `offline` won't be made available
    #downloadable: true
    # File matcher for checksum recalculation and detecting file changes
    #
    # default: size-ctime-inode
    # size-ctime-inode matcher should be used if possible,
    # might not work on windows
    #matcher: size-ctime-inode
    # size-ctime matcher should be used if stable fs inodes are
    # not available and might not work for fuse shares
    #matcher: size-ctime
    # size matcher should be used if you know what you are doing
    #matcher: size

# Extractor settings
#extractor:
  # Exclude file patterns
  #excludes:
    #- ...any string
  # Read exclude patterns from file
  #excludeFromFile: '{configDir}/excludes'
  #image:
    # default: [1920,1280,800,320,128]
    #previewSizes:
      #- ...any number
    # default: 80
    #previewQuality: 80
  #video:
    # used as preview size and preview filename
    #
    # default: 720
    #previewSize: 720
    # used as target video container and preview filename
    #
    # default: mp4
    #ext: mp4
    # overwrites previewSize.
    # E.g. -2:'min(ih,max(720,min(1080,ih*.5)))' for 720p <= height*0.5 <= 1080p or height, if height < 720
    #
    # default: "-2:'min(720,ih)'"
    #scale: "-2:'min(720,ih)'"
    # default: 30
    #frameRate: 30
    # default: 30
    #maxVideoBitRate: 30
    # default: libx264
    #videoEncoder: libx264
    # default: slow
    #preset: slow
    # default: baseline
    #profile: baseline
    # default: '3.0'
    #level: '3.0'
    # Additional ffmpeg args
    #addFfmpegArgs:
      #- ...any string
    # custom ffmpeg args for video conversion, replaces all other settings such previewSize, videoEncoder, addFfmpegArgs, ...
    #customFfmpegArgs:
      #- ...any string
  #apiServer:
    # URL of the API server
    #
    # In docker compose this is overwritten by GALLERY_API_SERVER env
    #
    # default: 'https://api.home-gallery.org'
    #url: 'https://api.home-gallery.org'
    # Timeout in seconds for each API request
    #
    # default: 30
    #timeout: 30
    # Concurrent requests to API server
    #
    # If you use a low power device you should reduce this value to 3
    #
    # default: 30
    #concurrent: 30
    #disable:
      #- similarDetection
      #- objectDetection
      #- faceDetection
  #geoReverse:
    # default: 'https://nominatim.openstreetmap.org'
    #url: 'https://nominatim.openstreetmap.org'
    #
    # Preffered address language of geo code reverse lookups
    #
    # default: ["en","de"]
    #addressLanguage:
      #- ...any string
  #useNative:
    # use libvips to resize images
    #- vipsthumbnail
    # use ImageMagick to resize images
    #- convert
    # Use ffprobe/ffmpeg from system
    #- ffprobe
    #- ffmpeg

# Storage settings
#storage:
  # default: '{cacheDir}/storage'
  #dir: '{cacheDir}/storage'

#database:
  # default: '{configDir}/{configPrefix}database.db'
  #file: '{configDir}/{configPrefix}database.db'
  # The full database creation is memory consuming. The default value is 2048 MB.
  # On memory errors or for larger photo collections (>50000 images) 4096 MB is recommended
  # Use less memory for smaller devices (e.g. Raspberry Pi Zero), e.g. 512 MB.
  # Node's default memory limit is 512 MB (changeable via --max-old-space-size node arg)
  #maxMemory: 2048
  # examples:
  #   * '*.xmp'
  #   * '*.svg'
  #excludes:
    #- ...any string
  #excludeFromFile: '{configDir}/excludes'
  #supportedTypes: image # one of: image, rawImage, video

#events:
  # default: '{configDir}/{configPrefix}events.db'
  #file: '{configDir}/{configPrefix}events.db'

#server:
  # default: 3000
  #port: 3000
  # default: '0.0.0.0'
  #host: '0.0.0.0'
  # Optional https certificate key
  #key: '{configDir}/server.key'
  # Optional https certificate
  #cert: '{configDir}/server.crt'
  # Prefix of application, including basePath of http page
  #prefix: /gallery
  # Prefix path for browser only. basePath is Overwritten by prefix
  # Use this if you use prefix by a http proxy which strips the prefix to / towards the gallery app
  #basePath: /
  # The public URL of the gallery instance
  #publicUrl: 'https://acme.com/gallery'
  # Open browser when server starts
  #openBrowser: true
  # Enable basic authentication users and ip whitelist rules which require no authentication
  #auth:
    #public:
      # Database filter for anonymous users
      #filter: 'year >= 2024 tag:public'
    #
    # Passwords can be in plain text, {SHA} or {SHA256-salted}.
    #
    # Hashed password can be generated via
    #   node -e "pw=process.argv[1];const {createHash,randomBytes}=require('crypto');salt=randomBytes(12);hash=createHash('sha256').update(salt.toString()+pw).digest('base64');console.log('{SHA256-salted}'+salt.toString('base64')+'.'+hash)" 'password'
    #   {SHA256-salted}FkcbhhcHYW0DdE9u.P9Ik9MG8ldtO0fzGB+RV186vi8PZMomsya5OWC0AEiA=
    #   node -e "pw=process.argv[1]||'';sha1=require('crypto').createHash('sha1').update(pw).digest('base64');console.log('{SHA}'+sha1)" password
    #   {SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=
    #
    #users:
      # Simple username:password pair
      #- johndoe: s3cr3t
      # User object with dedicated username, password properties
      #- username: guest
        #password: '{SHA256-salted}W1jrZgK81z06YLhA.qTSmeyYtPP19ZEpGiiAyVn61nly4jqbuuGoSefzLm98='
        # Database filter for the user
        #filter: 'year >= 2019 not tag:private'
    #
    # Rules when the request need authentication
    # First matching rule wins.
    #
    # For public gallery use
    # rules:
    #   - allow: localhost
    #   - deny: all
    #
    #rules:
      # [allow property] Allow rules without authentication like localhost
      #
      # examples:
      #   * all
      #   * localhost
      #   * '192.168/16'
      #- allow: all
      # [deny property] Deny rules which hosts requires authentication like all
      #
      # examples:
      #   * all
      #   * localhost
      #   * '192.168/16'
      #- deny: all
  # Import sources on server start
  #
  # default: true
  #importSources: true
  # Watch sources and import files on changes
  #
  # default: true
  #watchSources: true
  #api:
    #tree:
      # default: 4
      #monthGroupSize: 4
      # default: 4
      #ignoreRecentYears: 4

# Configuration for webapp module
#webapp:
  # Title of the webapp
  #
  # default: 'Home Gallery'
  #title: 'Home Gallery'
  #pluginManager:
    #
    # List of plugin urls to load
    #
    # default: []
    #plugins:
      #- ...any string
  #
  # List of feature flags to disable. By default all features are enabled.
  #
  # The feature flags can also be disabled by query param 'disabled'
  #
  # default: []
  #disabled:
    # Flags for edition tags
    #- serverEvents
    #- events
    #- edit
    # Disable database loading and use embedded entries only
    #- database
    # Enable progressive web application support
    #- pwa
    # Recommended performance features. Disable them on local dev issues
    #- offlineDatabase
    #- worker
    #- ...any string
  #
  # List of downloadable media sources. This list will be injected from the server
  #
  # default: []
  #sources:
    # [downloadable property] default: false
    #- downloadable: false
      #indexName: ""
  #
  # Customize pages
  #
  # default: []
  #pages:
    #disabled:
      #- edit
      #- date
      #- video
      #- map
      #- tag
      #- ...any string
    #
    # Customize single media view
    #
    # default: []
    #mediaView:
      #disabled:
        #- detail
        #- map
        #- similar
        #- annotation
        #- edit
        #- tag
        # Disables navigation to overview, prev and next
        #- nav
  #
  # Date format as in linux date command
  #   %b month name
  #   %d day of month, eg 01
  #   %m month, eg 12
  #   %Y 4 full year, eg 2025
  #   %y 2-digit year, eg 25
  #   %a short weekday name, eg. Mon
  #   %A full weekday name, eg. Monday
  #   %H hour eg 18
  #   %I hour eg 06 (12-hour clock)
  #   %p am/AM
  #   %P AM/PM
  #   %M minute, eg 06
  #   %S seconds, eg 45
  #
  # default: []
  #
  #format:
    # Date format
    #
    # default: '%d.%m.%Y'
    #date: '%d.%m.%Y'
    # Month year format
    #
    # default: '%b %Y'
    #monthYear: '%b %Y'
    # Year format
    #
    # default: '%Y'
    #year: '%Y'
    # time format
    #
    # default: '%H:%M:%S'
    #time: '%H:%M:%S'
    # time format with hour and minute
    #
    # default: '%H:%M'
    #hourMinute: '%H:%M'

# Plugin manager settings
#pluginManager:
  #
  # Load plugins from following directories.
  #
  # Each file or directory is handled as plugin
  #
  # example:
  #   * plugins
  #
  #dirs:
    #- ...any string
  #
  # List of dedicated plugin files
  #
  # example:
  #   * './my-plugin'
  #plugins:
    #- ...any string
  #
  # Disable plugins by name or by name.extension
  #
  # examples:
  #   * acmePlugin
  #   * acmePlugin.exentionName
  #disabled:
    #- ...any string

# Logger settings
#logger:
  # Console logger
  #- type: console
    # Log level
    #
    # default: info
    #level: info # one of: trace, debug, info, warn, error, fatal, silent
    # Use newline delimited JSON if format is set to json
    #format: json
  # File logger
  #- type: file
    # Log level
    #
    # default: debug
    #level: debug # one of: trace, debug, info, warn, error, fatal, silent
    # Log file path
    #
    # File logger format is in newline delimited JSON. See http://ndjson.org
    #file: '{configDir}/{configPrefix}gallery.log'