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:

1sources:
2  - ~/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

  1#
  2# HomeGallery configuration file
  3#
  4#
  5# Default configuration file is gallery.config.yml. JSON format is
  6# also supported (gallery.config.json)
  7#
  8# This is a comment, starting with hash tag and space ('# ')
  9# A default value starting with hash tag and variable ('#baseDir...')
 10#
 11# Directory value examples:
 12# - /absolute/directory
 13# - relative/directory/to/current/working/dir
 14# - ~/directory/in/your/home
 15# - ./relative/directory/to/configuration/file
 16#
 17# Variable replacements
 18#   baseDir: '~'
 19#   configDir: '{baseDir}/.config/home-gallery'
 20# configDir is replaced to '~/.config/home-gallery' and than to '$HOME/.config/home-gallery'
 21#
 22# Variables are overwritten by environment variables
 23#
 24# Variables are baseDir, configDir, configPrefix, cacheDir and dir in sources
 25# or environment variables GALLERY_BASE_DIR, GALLERY_CONFIG_DIR, GALLERY_CONFIG_PREFIX, GALLERY_CACHE_DIR
 26
 27#
 28# General
 29#
 30#baseDir: '~'
 31#configDir: '{baseDir}/.config/home-gallery'
 32# file prefix for index, database and events
 33#configPrefix: ''
 34#cacheDir: '{baseDir}/.cache/home-gallery'
 35
 36#
 37# Sources
 38#
 39# List of media source directories. These can be read only.
 40#
 41# All sources are used to build the gallery database. If you need
 42# different databases or gallery instances use different gallery
 43# configurations
 44sources:
 45  - dir: '{baseDir}/Pictures'
 46    #index: '{configDir}/{configPrefix}{basename(dir)}.idx'
 47    # excludes are using gitignore patterns
 48    #excludes:
 49      #- .DS_Store
 50      #- ._*
 51      #- '*.tmp'
 52      #- '*cache*'
 53    #excludeIfPresent: .galleryignore
 54    # excludeFromFile: '{configDir}/excludes'
 55    # Use maxFilesize to exclude big files such as videos to speedup initial setup
 56    # maxFilesize: 20M
 57    # If source directory/disk is offline/unmounted set it to true.
 58    # Offline sources require an index file. Previews and meta data
 59    # should be extracted first before marking a source offline
 60    #offline: false
 61    # Allows the original files to be downloaded via de webapp.  
 62    # This adds a link to images of this source in the details view.  
 63    # Sources set as `offline` won't be made available.  
 64    #downloadable: true
 65    # Filename matcher for checksum recalculation
 66    # size-ctime-inode: this matcher should be used if possible, might
 67    #                   not work on windows
 68    # size-ctime: this matcher should be used if stable fs inodes are
 69    #             not available and might not work for fuse shares
 70    # size: this matcher should be used if you know what you are doing
 71    #matcher: size-ctime-inode
 72
 73#
 74# Extractor settings
 75#
 76#extractor:
 77  # excludes:
 78  #   - *.xmp
 79  #   - *.svg
 80  # excludeFromFile: '{configDir}/excludes'
 81  # Preview image settings
 82  #image:
 83  #  previewSizes: [1920, 1280, 800, 320, 128]
 84  #  previewQuality: 80
 85  #video:
 86  #  previewSize: 720 # used as preview size and preview filename
 87  #  ext: mp4 # used as target video container and preview filename
 88  #  scale: -2:'min(720,ih)' # overwrites previewSize. E.g. -2:'min(ih,max(720,min(1080,ih*.5)))' for 720p <= height*0.5 <= 1080p or height, if height < 720
 89  #  frameRate: 30
 90  #  maxVideoBitRate: 4000 # in KB
 91  #  videoEncoder: libx264
 92  #  preset: slow
 93  #  profile: baseline
 94  #  level: '3.0'
 95  #  addFfmpegArgs: [...] # Additional ffmpeg args
 96  #  customFfmpegArgs: [...] # custom ffmpeg args for video conversion, replaces all other settings such previewSize, videoEncoder, addFfmpegArgs, ...
 97  # Api Server is used for image similarity, object and face detection
 98  #apiServer:
 99  #  url: https://api.home-gallery.org
100  #  timeout: 30
101  #  concurrent: 5
102  #  disable:
103  #    - similarDetection
104  #    - objectDetection
105  #    - faceDetection
106  #geoReverse:
107  #  url: https://nominatim.openstreetmap.org
108  #   Preffered address language of geo code reverse lookups
109  #   addressLanguage: [de, en-US] # for multiple languages
110  #  addressLanguage: [en, de]
111  # excludes are using gitignore patterns
112  #excludes: []
113  # Use native system commands. It is recoomended on armv6 and arm7 platform
114  # since the npm packages do not provide binaries for these platforms
115  #useNative:
116  #  - vipsthumbnail # use libvips to resize images
117  #  - convert # use ImageMagick to resize images
118  #  - ffprobe
119  #  - ffmpeg
120
121#
122# Storage and files configuration
123#
124#storage:
125  #dir: '{cacheDir}/storage'
126#database:
127  #file: '{configDir}/{configPrefix}database.db'
128  # The full database creation is memory consuming. The default value is 2048 MB.
129  # On memory errors or for larger photo collections (>50000 images) 4096 MB is recommended
130  # Use less memory for smaller devices (e.g. Raspberry Pi Zero), e.g. 512 MB.
131  # Node's default memory limit is 512 MB (changeable via --max-old-space-size node arg)
132  #maxMemory: 2048
133  # excludes:
134  #   - *.xmp
135  #   - *.svg
136  # excludeFromFile: '{configDir}/excludes'
137  # supportedTypes
138  #   - image
139  #   - rawImage
140  #   - video
141#events:
142  #file: '{configDir}/{configPrefix}events.db'
143
144#
145# Server configuration
146#
147#server:
148  #port: 3000
149  #host: '0.0.0.0'
150  # security configuration for https
151  # key: '{configDir}/server.key'
152  # cert: '{configDir}/server.crt'
153  # Open browser when server starts
154  #openBrowser: true
155  # Enable basic authentication users and ip whitelist rules which require no authentication
156  # First matching rule wins. Default rules are: allow: localhost and deny: all.
157  # Hashed password can be generated via
158  #   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'
159  #   {SHA256-salted}FkcbhhcHYW0DdE9u.P9Ik9MG8ldtO0fzGB+RV186vi8PZMomsya5OWC0AEiA=
160  #   node -e "pw=process.argv[1]||'';sha1=require('crypto').createHash('sha1').update(pw).digest('base64');console.log('{SHA}'+sha1)" password
161  #   {SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=
162  # auth:
163  #  public:
164  #    filter: 'year >= 2024 tag:public' # Database filter for non authenticated users and non whitelisted IPs
165  #  users:
166  #    - username: password
167  #    - username: '{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g='
168  #    - username: admin
169  #      password: '{SHA256-salted}FkcbhhcHYW0DdE9u.P9Ik9MG8ldtO0fzGB+RV186vi8PZMomsya5OWC0AEiA=' # passsword
170  #      filter: '' # no database filter for admin user
171  #    - username: guest
172  #      password: '{SHA256-salted}W1jrZgK81z06YLhA.qTSmeyYtPP19ZEpGiiAyVn61nly4jqbuuGoSefzLm98=' # guest
173  #      filter: 'year >= 2019 not tag:private'
174  #  rules:
175  #    - allow: localhost
176  #    - allow: '192.168/16'
177  #    - deny: all
178  # Prefix of application. E.g. /gallery
179  #prefix: /
180  # Prefix path for browser only. basePath is Overwritten by prefix
181  #basePath: /
182  #watchSources: true
183
184#
185# Webapp configuration
186#
187#webapp:
188  # Disabled webapp features
189  #disabled:
190    #- edit
191    #- serverEvents
192    #- pwa
193    #- offlineDatabase
194
195#
196# Plugin settings
197#
198#pluginManager:
199  # Directories to load. Each folder entry for or dir is handled as plugin
200  #dirs:
201    # First directory is default directory for plugin creation
202    #- plugins
203  # List of dedicated plugin files
204  #plugins:
205    #- pluginFile
206  #disabled:
207    #- acmePlugin
208    #- acmePlugin.extensionName
209
210# Plugin settings
211#plugin:
212  # Plugin name
213  #acme:
214    # Plugin setting
215    #prop: value
216
217logger:
218  # Currently console and file loggers are available
219  - type: console
220    # Log level could be one of trace, debug, info, warn, error, fatal, silent
221    level: info
222    # format: json
223  # File logger format is in newline delimited JSON. See http://ndjson.org
224  - type: file
225    # Log level could be one of trace, debug, info, warn, error, fatal, silent
226    level: debug
227    file: '{configDir}/{configPrefix}gallery.log'