All apps · 0 apps

PhotoPrism-Helper

Overview

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.

Readme

View on GitHub

PhotoPrism Helper

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

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

Install PhotoPrism-Helper on Unraid in a few clicks.

Find PhotoPrism-Helper in Community Apps on your Unraid server, review the template, and click Install. Unraid handles the Docker app or plugin setup from the published template.

Open the Apps tab on your Unraid server Search Community Apps for PhotoPrism-Helper Review the template variables and paths Click Install

Explore Unraid OS

Related apps

Explore more like this

Explore all

Productivity Utilities apps Photos apps

Links

Projectgithub.com Supportgithub.com Docker Hubhub.docker.com Templateraw.githubusercontent.com

Details

Repository

aerilym/photoprism-helper:master

Registry

https://hub.docker.com/r/aerilym/photoprism-helper/

Last Updated2026-02-15

First Seen2022-08-22

Runtime arguments

Network: bridge
Shell: sh
Privileged: false

Template configuration

Host PortPorttcp

The port the helper is hosted on. Container Port: 2343

Target: 2343
Default: 2342
Value: 2343

PhotoPrism Site URLVariable

Container Variable: PHOTOPRISM_SITE_URL

Target: PHOTOPRISM_SITE_URL
Default: http://localhost:2342
Value: http://localhost:2342

PhotoPrism UsernameVariable

The PhotoPrism username you want the helper to use for access.

Target: PHOTOPRISM_USERNAME
Default: admin
Value: admin

PhotoPrism PasswordVariable

The PhotoPrism password associated with the username.

Target: PHOTOPRISM_PASSWORD

Helper API KeyVariable

The API key you'll use to query the helper API.

Target: APIKEY
Default: testkey
Value: testkey

TimezoneVariable

The timezone of your instance.

Target: TIMEZONE
Default: Australia/Melbourne
Value: Australia/Melbourne

Import TimeoutVariable

The number of milliseconds the import function should wait for a success message before timing out.

Target: IMPORT_TIMEOUT
Default: 300000
Value: 300000

Auto ImportVariable

Enable/Disable the auto-import feature.

Target: AUTO_IMPORT
Default: false
Value: false

Auto Import Cron ScheduleVariable

The cron expression for when to run auto-import.

Target: AUTO_IMPORT_CRON
Default: 0 0 4 * * * *
Value: 0 0 5 * * * *

Index After Auto ImportVariable

Enable/Disable the index after auto-importing feature.

Target: INDEX_AFTER_AUTO_IMPORT
Default: false
Value: false

Auto IndexVariable

Enable/Disable the auto-index feature.

Target: AUTO_INDEX
Default: false
Value: false

Auto Index Cron ScheduleVariable

The cron expression for when to run auto-index.

Target: AUTO_INDEX_CRON
Default: 0 0 6 * * * *
Value: 0 0 5 * * * *

ISDOCKERVariable

Tells the helper instance if it is running in a Docker container. Container Variable: ISDOCKER

Default: 1
Value: 1

Logfile PathVariable

The logging file path.

Target: LOGFILE_PATH
Default: logs/local.log
Value: logs/local.log

Log Level - ConsoleVariable

The log level to apply to the console log.

Target: LOGLEVEL_CONSOLE
Default: info
Value: info

Log Level - FileVariable

The log level to apply to the file log.

Target: LOGLEVEL_FILE
Default: error
Value: error

Send Errors to the DeveloperVariable

Enable/Disable sending errors/exceptions to the dev.

Target: SEND_ERRORS
Default: true
Value: true

Error Log URL (Dev)Variable

The URL to send errors to. (Don't change unless you're running your own fork of the helper)

Target: ERROR_LOG_URL

Error Log Key (Dev)Variable

The API key sent with error logs to the external server.

Target: ERROR_LOG_KEY

Anonymise Error LogsVariable

Enable/Disable anonymising externally sent error logs.

Target: ERROR_LOG_IDENTITY_ANONYMISED
Default: false
Value: false

Send Options in Error LogVariable

Enable/Disable sending your configuration options with externally sent errors.

Target: ERROR_LOG_IDENTITY_SEND_OPTIONS
Default: true
Value: true

Add Logging to External ServerVariable

Enable/Disable sending logs to an external log server.

Target: EXTERNAL_LOG
Default: false
Value: false

External Log DepthVariable

The log level to apply to the external log.

Target: EXTERNAL_LOG_DEPTH
Default: info
Value: info

External Log URLVariable

The URL of the external log server.

Target: EXTERNAL_LOG_URL

External Log API KeyVariable

The API key sent with logs sent to the external log server.

Target: EXTERNAL_LOG_KEY

Anonymise External LogsVariable

Enable/Disable anonymising externally sent logs.

Target: EXTERNAL_LOG_IDENTITY_ANONYMISED
Default: false
Value: false

Send Options in External LogsVariable

Enable/Disable sending your configuration options with externally sent logs.

Target: EXTERNAL_LOG_IDENTITY_SEND_OPTIONS
Default: true
Value: true

Library

Curated

Categories