Install

HomeGallery is a command line tool to init the configuration, start the web server at localhost:3000 and import the media sources. To run your gallery at home you need to

  • install the software

  • initialize the configuration

  • run the local web server

HomeGallery can run through

  • prebuilt binary on Linux, Mac on Windows

  • as docker container

  • via docker-compose

  • application bundle for Linux, Mac on Windows

  • generic application bundle

  • from source

Installation Tutorial

Prebuilt binaries

Download the binary for your platform:

Other download options can be found here. and there are also unstable releases from the current development stage.

A prebuilt binary is a command line application through a selfextracting archive. On the first start it extracts all required files to a temporary directory and starts the gallery CLI. Please be patient on the first start. Future starts skip the extraction and the gallery starts faster.

The gallery CLI requires a gallery.config.yml configuration file and it is created if missing. See Configuration section for details and comments.

By default the HomeGallery stores the configuration files in ~/.config/home-gallery. The generated preview and extracted meta data files are stored in ~/.cache/home-gallery/storage. For docker containers theses directories are different.

Note

On Windows the app might be blocked by the anti virus application and should be allowed manually. The extracted files can be found at %temp% directory.

Note

On Mac the app might be blocked the OS and should be allowed manually. See Open a Mac app from an unidentified developer.

Quickstart

1curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
2chmod 755 gallery
3./gallery run init --source ~/Pictures
4./gallery run server &

While your media files are imported open your HomeGallery at localhost:3000 in your browser.

Run the CLI

The CLI with all commands of the gallery binary is started via

1./gallery -h

Docker

HomeGallery offers docker image at xemle/home-gallery (amd64, arm64, arm/v7 and arm/v6 architecture). These image are build via GitHub actions.

Data volume structure

The gallery application is located at /app whereas the data is stored in /data within the container. The /data folder has following structure:

`-- /data - Docker data volume
  +-- sources - Your media file sources or other volumne mounts
  +-- config - File index, database and configuration files
  | `-- gallery.config.yml - Main configuration file
  `-- storage - Preview images and meta data

The media volumes should be mounted into the /data directory. Eg. mount your host directory ~/Pictures to /data/Pictures in the container and add it as source to your gallery.config.yml.

To avoid user permission problems it is advisable to run the container with your user and group id via -u parameter.

Quickstart

1mkdir -p data
2alias gallery="docker run -ti --rm \
3  -v $(pwd)/data:/data \
4  -v $HOME/Pictures:/data/Pictures \
5  -u $(id -u):$(id -g) \
6  -p 3000:3000 xemle/home-gallery"
7gallery run init --source /data/Pictures
8gallery run server

While your media files are imported open your HomeGallery at localhost:3000 in your browser.

Note

The docker container is configured to poll image sources each 5 minutes for compatibility reasons of slow or large media volumes. Check if inotify through disabled polling by GALLERY_WATCH_POLL_INTERVAL=0 is working for you.

Run the CLI

The CLI with all commands via docker is started by

1gallery -h

Upgrade the gallery

To upgrade the gallery software, please stop your current container, pull the latest image and start a new container.

Please run the import command after an application upgrade to rebuild the database. This step will add new features and fix missing database entries. If all your media is already imported the import can be done while the server is running

1# stop the current container
2docker pull xemle/home-gallery
3gallery run import
4gallery run server

Custom image

You can customize and build the docker image by your own

git clone https://github.com/xemle/home-gallery.git
cd home-gallery
docker build -t home-gallery .

Docker Compose

Docker compose simplifies the configuration of containers and connected services. Following example starts the HomeGallery with a local API server.

 1version: "3.9"
 2services:
 3  api:
 4    # custom build via
 5    #build: packages/api-server
 6    image: xemle/home-gallery-api-server
 7    environment:
 8      # TensorflowJS backends
 9      # - cpu: slowest and best support
10      # - wasm: good perfromance for arm64 and amd64 platforms
11      # - node: best performance on amd64 platform
12      #- BACKEND=cpu
13      - BACKEND=wasm
14      #- BACKEND=node
15  gallery:
16    # custom build via
17    #build: .
18    image: xemle/home-gallery
19    environment:
20      - GALLERY_API_SERVER=http://api:3000
21      - GALLERY_API_SERVER_CONCURRENT=1 # for SoC devices like Rasperry Pi. Use 5 otherwise
22      - GALLERY_API_SERVER_TIMEOUT=60 # for SoC devices like Rasperry Pi. Use 30 otherwise
23      #- GALLERY_USE_NATIVE=ffprobe,ffmpeg,vipsthumbnail # On issues with sharp resizer
24      - GALLERY_OPEN_BROWSER=false
25      # Use polling for safety of possible network mounts. Try 0 to use inotify via fs.watch
26      - GALLERY_WATCH_POLL_INTERVAL=300
27    volumes:
28      - ./data:/data
29      # Mount your media directories below /data
30      - ${HOME}/Pictures:/data/Pictures
31    ports:
32      - "3000:3000"
33    user: "${CURRENT_USER}"
34    entrypoint: ['node', '/app/gallery.js']
35    command: ['run', 'server']

Note

By default the wasm backend for the API server is used for best support on most platforms (SoS, NAS, cloud and desktop). Use node backend for best performance on amd64 CPUs like desktops. Please validate that the backend node works for you.

Quickstart

1mkdir -p data
2echo "CURRENT_USER=$(id -u):$(id -g)" >> .env
3docker compose run gallery run init --source /data/Pictures
4docker compose up -d

Note

The docker container is configured to poll image sources each 5 minutes for compatibility reasons of slow or large media volumes. Check if inotify through disabled polling by GALLERY_WATCH_POLL_INTERVAL=0 is working for you.

Run the CLI

The CLI with all commands is started via docker compose

1docker compose run gallery -h

This CLI is attached to the pseudo-tty. To run it as background job like in cron jobs, pleas use -T argument

1docker compose run -T gallery -h

Upgrade the gallery

To upgrade the gallery software, please pull the latest container and restart your services.

Please run the import command after an application upgrade to rebuild the database. This step will add new features and fix missing database entries. If all your media is already imported the import can be done while the server is running

1docker compose pull
2docker compose run gallery run import
3# For cron update task use -T to disable pseudo-tty allocation
4#docker compose run -T gallery run import
5docker compose up -d

Application bundle

HomeGallery can be also downloaded as tar.gz archive from dl.home-gallery.org/dist for Linux, Mac and Windows. These tar.gz archives are the same as the prebuilt binaries. You have to start the main script manually.

These tar balls include binaries for the given platform

  • NodeJS

  • ffmpeg and ffprobe

  • sharp

  • exiftool

Note

On Linux and Mac perl needs to be installed and in the PATH environment

Quickstart

1curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64.tar.gz -o home-gallery.tar.gz
2tar xvf home-gallery.tar.gz
3cd home-gallery
4node gallery.js run init --source ~/Pictures
5node gallery.js run server &

While your media files are imported open your HomeGallery at localhost:3000 in your browser.

Run the CLI

The CLI with all commands of the app bundle is started via

1node gallery.js -h

Upgrade the gallery

To upgrade the gallery software, please stop your current server, download the latest version and start the new version.

Please run the import command to rebuild the database. This step will add new features and fix missing database entries. If all your media is already imported the import can be done in parallel with the server command.

1# stop the current server
2mv home-gallery home-gallery.old
3curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64.tar.gz -o home-gallery.tar.gz
4tar xvf home-gallery.tar.gz
5cd home-gallery
6node gallery.js import
7node gallery.js run server &

Generic application bundle

The generic archive of HomeGallery contains all JS resources without binary dependencies like node.js, sharp, ffmpeg or ffprobe.

It requires following binaryies preinstalled on your system:

  • NodeJS LTS v16 (v14 should also work)

  • perl

  • ffmpeg

  • ffprobe

  • vipsthumbnail (via vips-tools) or convert (via ImageMagick)

Further the extractor has to be configured to use these native commands. See Configuration section for configuration details.

Quickstart

1curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-all-generic.tar.gz -o home-gallery.tar.gz
2tar xf home-gallery.tar.gz
3cd home-gallery
4./gallery.js run init --source ~/Pictures
5# Edit gallery.config.yml and set native commands, see example below
6./gallery.js run server &

Run the CLI

The CLI with all commands of the generic bundle is started via

1./gallery.js -h

Upgrade the gallery

To upgrade the gallery software, please stop your current server, download the latest version and start the new version.

Please run the import command to rebuild the database. This step will add new features and fix missing database entries. If all your media is already imported the import can be done in parallel with the server command.

1# stop the current server
2# downlaod and extract the newest generic bundle
3# change directory to home-gallery
4./gallery.js run import
5./gallery.js run server &

Example configuration part for extractor:

1extractor:
2  useNative:
3    - vipsthumbnail
4    - ffprobe
5    - ffmpeg

Source code

If you like to fix and tweak HomeGallery you can checkout the source code, install the npm dependencies and build the packages.

Quickstart

1git clone https://github.com/xemle/home-gallery.git
2cd home-gallery
3npm install --force
4npm run build
5./gallery.js run init --source ~/Pictures
6./gallery.js run server

Run the CLI

The CLI with all commands from source is started via

1./gallery.js -h

Upgrade the gallery

To upgrade the gallery software, please stop your current server, fetch the latest master, build the sources and start the new version.

Please run the import command to rebuild the database. This step will add new features and fix missing database entries. If all your media is already imported the import can be done in parallel with the server command.

1# Stop the current server
2# Got to the source directory
3git pull
4npm i
5npm run clean
6npm run build
7./gallery.js run import
8./gallery.js run server