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

curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
chmod 755 gallery
./gallery run init --source ~/Pictures
./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

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.

# stop the current server
mv gallery gallery.old
curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
chmod 755 gallery
./gallery run import
./gallery run server &

Docker

HomeGallery offers docker image at xemle/home-gallery (amd64 and arm64 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

mkdir -p data/config
alias gallery="docker run -ti --rm \
  -v $(pwd)/data:/data \
  -v $HOME/Pictures:/data/Pictures \
  -u $(id -u):$(id -g) \
  -p 3000:3000 xemle/home-gallery"
gallery run init --source /data/Pictures
gallery 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

# stop the current container
docker pull xemle/home-gallery
gallery run import
gallery 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.

version: "3.9"
services:
  api:
    # custom build via
    #build: packages/api-server
    image: xemle/home-gallery-api-server
    environment:
      # TensorflowJS backends
      # - cpu: slowest and best support
      # - wasm: good perfromance for arm64 and amd64 platforms
      # - node: best performance on amd64 platform
      #- BACKEND=cpu
      - BACKEND=wasm
      #- BACKEND=node
  gallery:
    # custom build via
    #build: .
    image: xemle/home-gallery
    environment:
      - GALLERY_API_SERVER=http://api:3000
      - GALLERY_API_SERVER_CONCURRENT=1 # for SoC devices like Rasperry Pi. Use 5 otherwise
      - GALLERY_API_SERVER_TIMEOUT=60 # for SoC devices like Rasperry Pi. Use 30 otherwise
      #- GALLERY_USE_NATIVE=ffprobe,ffmpeg,vipsthumbnail # On issues with sharp resizer
      - GALLERY_OPEN_BROWSER=false
      # Use polling for safety of possible network mounts. Try 0 to use inotify via fs.watch
      - GALLERY_WATCH_POLL_INTERVAL=300
    volumes:
      - ./data:/data
      # Mount your media directories below /data
      - ${HOME}/Pictures:/data/Pictures
    ports:
      - "3000:3000"
    user: "${CURRENT_USER}"
    entrypoint: ['node', '/app/gallery.js']
    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

mkdir -p data/config
echo "CURRENT_USER=$(id -u):$(id -g)" >> .env
docker compose run gallery run init --source /data/Pictures
docker 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

docker 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

docker 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

docker compose pull
docker compose run gallery run import
# For cron update task use -T to disable pseudo-tty allocation
#docker compose run -T gallery run import
docker 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

curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64.tar.gz -o home-gallery.tar.gz
tar xvf home-gallery.tar.gz
cd home-gallery
node gallery.js run init --source ~/Pictures
node 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.

# stop the current server
mv home-gallery home-gallery.old
curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64.tar.gz -o home-gallery.tar.gz
tar xvf home-gallery.tar.gz
cd home-gallery
node gallery.js import
node 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

curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-all-generic.tar.gz -o home-gallery.tar.gz
tar xf home-gallery.tar.gz
cd home-gallery
./gallery.js run init --source ~/Pictures
# Edit gallery.config.yml and set native commands, see example below
./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.

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

Example configuration part for extractor:

extractor:
  useNative:
    - vipsthumbnail
    - ffprobe
    - 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

git clone https://github.com/xemle/home-gallery.git
cd home-gallery
npm install --force
npm run build
./gallery.js run init --source ~/Pictures
./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.

# Stop the current server
# Got to the source directory
git pull
npm i
npm run clean
npm run build
./gallery.js run import
./gallery.js run server

Other systems

Quickstart using Azure Container Instance (ACI)

Run with Azure CloudShell:

# vars
ACI_PERS_RESOURCE_GROUP=HomeGalleryRG01
ACI_PERS_STORAGE_ACCOUNT_NAME=mystorageaccount123
ACI_PERS_LOCATION=eastus
ACI_PERS_SHARE_NAME=acishare

# create storage
az storage account create --resource-group $ACI_PERS_RESOURCE_GROUP --name $ACI_PERS_STORAGE_ACCOUNT_NAME --location $ACI_PERS_LOCATION --sku Standard_LRS
# create share
az storage share create --name $ACI_PERS_SHARE_NAME --account-name $ACI_PERS_STORAGE_ACCOUNT_NAME
# var for storage key
STORAGE_KEY=$(az storage account keys list --resource-group $ACI_PERS_RESOURCE_GROUP --account-name $ACI_PERS_STORAGE_ACCOUNT_NAME --query "[0].value" --output tsv)

# create container and mapping of the share
az container create \
    --resource-group $ACI_PERS_RESOURCE_GROUP \
    --name homegallery-01 \
    --image xemle/home-gallery  \
    --dns-name-label homegallery-01 \
    --ports 3000 \
    --command-line "node /app/gallery.js run server" \
    --azure-file-volume-account-name $ACI_PERS_STORAGE_ACCOUNT_NAME \
    --azure-file-volume-account-key $STORAGE_KEY \
    --azure-file-volume-share-name $ACI_PERS_SHARE_NAME \
    --azure-file-volume-mount-path /data

In Azure, use the share within the resource group to create /data/Pictures, as well as /data/config/gallery.config.yml

Use the acishare to upload images.