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