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
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 gallery gallery.old
3curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
4chmod 755 gallery
5./gallery run import
6./gallery run server &
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 # On low powered devices
22 #- GALLERY_API_SERVER_TIMEOUT=60 # On low powered devices
23 - GALLERY_OPEN_BROWSER=false
24 # Use polling for safety of possible network mounts. Try 0 to use inotify via fs.watch
25 - GALLERY_WATCH_POLL_INTERVAL=300
26 volumes:
27 - ./data:/data
28 # Mount your media directories below /data
29 - ${HOME}/Pictures:/data/Pictures
30 ports:
31 - "3000:3000"
32 user: "${CURRENT_USER}"
33 entrypoint: ['node', '/app/gallery.js']
34 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