PhotoPrism Helper

PhotoPrism Helper is an unofficial companion tool created for use alongside PhotoPrism. This project isn't associated with the PhotoPrism project, it's just a companion tool created to extend the functionality of PhotoPrism.

Feature Overview

• Middleware API
• Web Interface
• Automation of PhotoPrism features

The current main features are API endpoints for importing and indexing content, as well as setting up cron tasks to enable automated importing and indexing.

Getting Started

The application is designed to be used in a docker container or hosted on any local machine. After cloning the repository you can set up, build, and run the project by doing the following:

Start by installing all the dependencies:

npm install

Build the project:

npm run build

or

Build the docker image:

docker build -t aerilym/photoprism-helper .

Environment Variables

A list of possible environment variables is available: .env.template

Variable	Default	Description
PHOTOPRISM_SITE_URL	http://localhost:2342/	The URL of your PhotoPrism instance.
HOSTPORT	2343	The port the helper is hosted on.
PHOTOPRISM_USERNAME	admin	The PhotoPrism username you want the helper to use for access.
PHOTOPRISM_PASSWORD		The PhotoPrism password associated with the username.
APIKEY	testkey	The API key you'll use to query the helper API.
TIMEZONE	Melbourne/Australia	The timezone of your instance.
IMPORT_TIMEOUT	300000	The number of milliseconds the import function should wait for a success message before timing out.
MOVE_ON_IMPORT	false	Enable/Disable moving files on import.
AUTO_IMPORT	false	Enable/Disable the auto-import feature.
AUTO_IMPORT_CRON	0 0 4 * * * *	The cron expression for when to run auto-import.
INDEX_AFTER_AUTO_IMPORT	false	Enable/Disable the index after auto-importing feature.
INDEX_TIMEOUT	300000	The number of milliseconds the index function should wait for a success message before timing out.
INDEX_RESCAN	false	Enable/Disable rescanining when indexing (From PhotoPrism settings).
INDEX_SKIP_ARCHIVED	false	Enable/Disable skipping archive (From PhotoPrism settings).
AUTO_INDEX	false	Enable/Disable the auto-index feature.
AUTO_INDEX_CRON	0 0 6 * * * *	The cron expression for when to run auto-index.
LOGFILE_PATH	logs/local.log	The logging file path.
LOGLEVEL_CONSOLE	info	The log level to apply to the console log.
LOGLEVEL_FILE	error	The log level to apply to the file log.
SEND_ERRORS	true	Enable/Disable sending errors/exceptions to the dev.
ERROR_LOG_URL		The URL to send errors to. (Don't change unless you're running your own fork of the helper)
ERROR_LOG_KEY		The API key sent with error logs to the external server.
ERROR_LOG_ANONYMISE	false	Enable/Disable anonymising externally sent error logs.
ERROR_LOG_OPTIONS	true	Enable/Disable sending your configuration options with externally sent errors.
EXTERNAL_LOG	false	Enable/Disable sending logs to an external log server.
EXTERNAL_LOG_DEPTH	info	The log level to apply to the external log.
EXTERNAL_LOG_URL		The URL of the external log server.
EXTERNAL_LOG_KEY		The API key sent with logs sent to the external log server.
EXTERNAL_LOG_ANONYMISE	false	Enable/Disable anonymising externally sent logs.
EXTERNAL_LOG_OPTIONS	true	Enable/Disable sending your configuration options with externally sent logs.

If enabled, the configuration options sent with externally sent errors and logs are:

TBD

Building a Local Install

Create a .env file, based on the .env.template file and fill it with your options.

At a minimum, the USER AND PASS environment variables need to be set, but BASEURL will be required if your PhotoPrism instance isn't available on localhost:2342. Read more about environment variables.

Run the following command to build the application from the source files:

npm run build

This will build the application and output the files to build/

Once the application is built, run the following command to start it:

npm run start:prd

The application will now run and be available at the address and port you specified in .env

If you're familiar with Node and TypeScript feel free to isolate the build folder to minimise the installation.

Docker

The container can be created using the Dockerfile available, or by using the container available as a GitHub Package or DockerHub.

The container can be easily built from the source code by running:

npm run build:docker

API Documentation

Authentication

All requests must contain an authorization header with a set API key as such:

Authorization: "Bearer <APIKEY>"

Endpoints

Import

POST /import

Index

POST /index

Stats

GET /stats