1.0.3 • Published 11 months ago

photoprism-helper v1.0.3

Weekly downloads
-
License
ISC
Repository
-
Last release
11 months ago

PhotoPrism Helper

Build CodeQL Publish Docker image CodeFactor Known Vulnerabilities

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

VariableDefaultDescription
PHOTOPRISM_SITE_URLhttp://localhost:2342/The URL of your PhotoPrism instance.
HOSTPORT2343The port the helper is hosted on.
PHOTOPRISM_USERNAMEadminThe PhotoPrism username you want the helper to use for access.
PHOTOPRISM_PASSWORDThe PhotoPrism password associated with the username.
APIKEYtestkeyThe API key you'll use to query the helper API.
TIMEZONEMelbourne/AustraliaThe timezone of your instance.
IMPORT_TIMEOUT300000The number of milliseconds the import function should wait for a success message before timing out.
MOVE_ON_IMPORTfalseEnable/Disable moving files on import.
AUTO_IMPORTfalseEnable/Disable the auto-import feature.
AUTO_IMPORT_CRON0 0 4 * * * *The cron expression for when to run auto-import.
INDEX_AFTER_AUTO_IMPORTfalseEnable/Disable the index after auto-importing feature.
INDEX_TIMEOUT300000The number of milliseconds the index function should wait for a success message before timing out.
INDEX_RESCANfalseEnable/Disable rescanining when indexing (From PhotoPrism settings).
INDEX_SKIP_ARCHIVEDfalseEnable/Disable skipping archive (From PhotoPrism settings).
AUTO_INDEXfalseEnable/Disable the auto-index feature.
AUTO_INDEX_CRON0 0 6 * * * *The cron expression for when to run auto-index.
LOGFILE_PATHlogs/local.logThe logging file path.
LOGLEVEL_CONSOLEinfoThe log level to apply to the console log.
LOGLEVEL_FILEerrorThe log level to apply to the file log.
SEND_ERRORStrueEnable/Disable sending errors/exceptions to the dev.
ERROR_LOG_URLThe URL to send errors to. (Don't change unless you're running your own fork of the helper)
ERROR_LOG_KEYThe API key sent with error logs to the external server.
ERROR_LOG_ANONYMISEfalseEnable/Disable anonymising externally sent error logs.
ERROR_LOG_OPTIONStrueEnable/Disable sending your configuration options with externally sent errors.
EXTERNAL_LOGfalseEnable/Disable sending logs to an external log server.
EXTERNAL_LOG_DEPTHinfoThe log level to apply to the external log.
EXTERNAL_LOG_URLThe URL of the external log server.
EXTERNAL_LOG_KEYThe API key sent with logs sent to the external log server.
EXTERNAL_LOG_ANONYMISEfalseEnable/Disable anonymising externally sent logs.
EXTERNAL_LOG_OPTIONStrueEnable/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