From c6c4210dd2820449952340f7587663361df51e45 Mon Sep 17 00:00:00 2001 From: "Patrik J. Braun" Date: Fri, 7 Feb 2020 13:59:36 +0100 Subject: [PATCH] improving settings documentation --- MANPAGE.md | 234 ++++++++++++++++++++++++++-- README.md | 3 +- docker/README.md | 1 + gulpfile.ts | 8 +- src/common/config/private/Config.ts | 4 +- 5 files changed, 235 insertions(+), 15 deletions(-) diff --git a/MANPAGE.md b/MANPAGE.md index 5dca3924..f2a40aa4 100644 --- a/MANPAGE.md +++ b/MANPAGE.md @@ -9,7 +9,7 @@ Usage: [options] Meta cli options: --help prints this manual --config-path sets the config file location ---config-attachDefs prints the defaults to the config file +--config-attachState prints the value state (default, readonly, volatile, etc..) to the config file --config-attachDesc prints description to the config file --config-rewrite-cli updates the config file with the options from cli switches --config-rewrite-env updates the config file with the options from environmental variables @@ -45,8 +45,9 @@ App CLI options: --Server-Threading-thumbnailThreads Number of threads that are used to generate thumbnails. If 0, number of 'CPU cores -1' threads will be used. (default: 0) --Server-Database-type (default: 'sqlite') --Server-Database-dbFolder (default: 'db') - --Server-Database-mysql-host (default: '') - --Server-Database-mysql-database (default: '') + --Server-Database-mysql-host (default: 'localhost') + --Server-Database-mysql-port (default: 3306) + --Server-Database-mysql-database (default: 'pigallery2') --Server-Database-mysql-username (default: '') --Server-Database-mysql-password (default: '') --Server-Sharing-updateTimeout (default: 300000) @@ -61,7 +62,7 @@ App CLI options: --Server-Log-level (default: 'info') --Server-Log-sqlLevel (default: 'error') --Server-Jobs-maxSavedProgress Job history size (default: 10) - --Server-Jobs-scheduled (default: [{"name":"Indexing","jobName":"Indexing","config":{},"allowParallelRun":false,"trigger":{"type":1}},{"name":"Thumbnail Generation","jobName":"Thumbnail Generation","config":{"sizes":[240]},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Indexing"}},{"name":"Photo Converting","jobName":"Photo Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Thumbnail Generation"}},{"name":"Video Converting","jobName":"Video Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Photo Converting"}},{"name":"Temp Folder Cleaning","jobName":"Temp Folder Cleaning","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Photo Converting"}}]) + --Server-Jobs-scheduled (default: [{"name":"Indexing","jobName":"Indexing","config":{},"allowParallelRun":false,"trigger":{"type":1}},{"name":"Thumbnail Generation","jobName":"Thumbnail Generation","config":{"sizes":[240]},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Indexing"}},{"name":"Photo Converting","jobName":"Photo Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Thumbnail Generation"}},{"name":"Video Converting","jobName":"Video Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Photo Converting"}},{"name":"Temp Folder Cleaning","jobName":"Temp Folder Cleaning","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Video Converting"}}]) --Client-applicationTitle (default: 'PiGallery 2') --Client-publicUrl (default: '') --Client-urlBase (default: '') @@ -77,7 +78,7 @@ App CLI options: --Client-Sharing-passwordProtected (default: true) --Client-Map-enabled (default: true) --Client-Map-useImageMarkers (default: true) - --Client-Map-mapProvider (default: 0) + --Client-Map-mapProvider (default: 'OpenStreetMap') --Client-Map-mapboxAccessToken (default: '') --Client-Map-customLayers (default: [{"name":"street","url":""}]) --Client-RandomPhoto-enabled (default: true) @@ -120,9 +121,11 @@ Environmental variables: Server-Threading-thumbnailThreads Number of threads that are used to generate thumbnails. If 0, number of 'CPU cores -1' threads will be used. (default: 0) Server-Database-type (default: 'sqlite') Server-Database-dbFolder (default: 'db') - Server-Database-mysql-host (default: '') + Server-Database-mysql-host (default: 'localhost') MYSQL_HOST same as Server-Database-mysql-host - Server-Database-mysql-database (default: '') + Server-Database-mysql-port (default: 3306) + MYSQL_PORT same as Server-Database-mysql-port + Server-Database-mysql-database (default: 'pigallery2') MYSQL_DATABASE same as Server-Database-mysql-database Server-Database-mysql-username (default: '') MYSQL_USERNAME same as Server-Database-mysql-username @@ -140,7 +143,7 @@ Environmental variables: Server-Log-level (default: 'info') Server-Log-sqlLevel (default: 'error') Server-Jobs-maxSavedProgress Job history size (default: 10) - Server-Jobs-scheduled (default: [{"name":"Indexing","jobName":"Indexing","config":{},"allowParallelRun":false,"trigger":{"type":1}},{"name":"Thumbnail Generation","jobName":"Thumbnail Generation","config":{"sizes":[240]},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Indexing"}},{"name":"Photo Converting","jobName":"Photo Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Thumbnail Generation"}},{"name":"Video Converting","jobName":"Video Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Photo Converting"}},{"name":"Temp Folder Cleaning","jobName":"Temp Folder Cleaning","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Photo Converting"}}]) + Server-Jobs-scheduled (default: [{"name":"Indexing","jobName":"Indexing","config":{},"allowParallelRun":false,"trigger":{"type":1}},{"name":"Thumbnail Generation","jobName":"Thumbnail Generation","config":{"sizes":[240]},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Indexing"}},{"name":"Photo Converting","jobName":"Photo Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Thumbnail Generation"}},{"name":"Video Converting","jobName":"Video Converting","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Photo Converting"}},{"name":"Temp Folder Cleaning","jobName":"Temp Folder Cleaning","config":{},"allowParallelRun":false,"trigger":{"type":4,"afterScheduleName":"Video Converting"}}]) Client-applicationTitle (default: 'PiGallery 2') Client-publicUrl (default: '') Client-urlBase (default: '') @@ -156,7 +159,7 @@ Environmental variables: Client-Sharing-passwordProtected (default: true) Client-Map-enabled (default: true) Client-Map-useImageMarkers (default: true) - Client-Map-mapProvider (default: 0) + Client-Map-mapProvider (default: 'OpenStreetMap') Client-Map-mapboxAccessToken (default: '') Client-Map-customLayers (default: [{"name":"street","url":""}]) Client-RandomPhoto-enabled (default: true) @@ -177,4 +180,215 @@ Environmental variables: Client-Faces-enabled (default: true) Client-Faces-keywordsToPersons (default: true) Client-Faces-writeAccessMinRole (default: 'Admin') -``` \ No newline at end of file +``` + + ### `config.json` sample: +```json +{ + "Server": { + "sessionSecret": [], + "port": 80, + "host": "0.0.0.0", + "Media": { + "//[folder]": "Images are loaded from this folder (read permission required)", + "folder": "demo/images", + "//[tempFolder]": "Thumbnails, coverted photos, videos will be stored here (write permission required)", + "tempFolder": "demo/tmp", + "photoProcessingLibrary": "sharp", + "Video": { + "transcoding": { + "bitRate": 5242880, + "resolution": 720, + "fps": 25, + "codec": "libx264", + "format": "mp4" + } + }, + "Photo": { + "Converting": { + "//[onTheFly]": "Converts photos on the fly, when they are requested.", + "onTheFly": true, + "resolution": 1080 + } + }, + "Thumbnail": { + "//[qualityPriority]": "if true, photos will have better quality.", + "qualityPriority": true, + "personFaceMargin": 0.6 + } + }, + "Threading": { + "//[enabled]": "App can run on multiple thread", + "enabled": true, + "//[thumbnailThreads]": "Number of threads that are used to generate thumbnails. If 0, number of 'CPU cores -1' threads will be used.", + "thumbnailThreads": 0 + }, + "Database": { + "type": "sqlite", + "dbFolder": "db", + "mysql": { + "host": "localhost", + "port": 3306, + "database": "pigallery2", + "username": "", + "password": "" + } + }, + "Sharing": { + "updateTimeout": 300000 + }, + "//[sessionTimeout]": "unit: ms", + "sessionTimeout": 604800000, + "Indexing": { + "folderPreviewSize": 2, + "cachedFolderTimeout": 3600000, + "reIndexingSensitivity": "low", + "//[excludeFolderList]": "If an entry starts with '/' it is treated as an absolute path. If it doesn't start with '/' but contains a '/', the path is relative to the image directory. If it doesn't contain a '/', any folder with this name will be excluded.", + "excludeFolderList": [], + "//[excludeFileList]": "Any folder that contains a file with this name will be excluded from indexing.", + "excludeFileList": [] + }, + "//[photoMetadataSize]": "only this many bites will be loaded when scanning photo for metadata", + "photoMetadataSize": 524288, + "Duplicates": { + "listingLimit": 1000 + }, + "Log": { + "level": "info", + "sqlLevel": "error" + }, + "Jobs": { + "//[maxSavedProgress]": "Job history size", + "maxSavedProgress": 10, + "scheduled": [ + { + "name": "Indexing", + "jobName": "Indexing", + "config": {}, + "allowParallelRun": false, + "trigger": { + "type": "never" + } + }, + { + "name": "Thumbnail Generation", + "jobName": "Thumbnail Generation", + "config": { + "sizes": [ + 240 + ] + }, + "allowParallelRun": false, + "trigger": { + "type": "after", + "afterScheduleName": "Indexing" + } + }, + { + "name": "Photo Converting", + "jobName": "Photo Converting", + "config": {}, + "allowParallelRun": false, + "trigger": { + "type": "after", + "afterScheduleName": "Thumbnail Generation" + } + }, + { + "name": "Video Converting", + "jobName": "Video Converting", + "config": {}, + "allowParallelRun": false, + "trigger": { + "type": "after", + "afterScheduleName": "Photo Converting" + } + }, + { + "name": "Temp Folder Cleaning", + "jobName": "Temp Folder Cleaning", + "config": {}, + "allowParallelRun": false, + "trigger": { + "type": "after", + "afterScheduleName": "Video Converting" + } + } + ] + } + }, + "Client": { + "applicationTitle": "PiGallery 2", + "publicUrl": "", + "urlBase": "", + "Search": { + "enabled": true, + "instantSearchEnabled": true, + "InstantSearchTimeout": 3000, + "instantSearchCacheTimeout": 3600000, + "searchCacheTimeout": 3600000, + "AutoComplete": { + "enabled": true, + "maxItemsPerCategory": 5, + "cacheTimeout": 3600000 + } + }, + "Sharing": { + "enabled": true, + "passwordProtected": true + }, + "Map": { + "enabled": true, + "useImageMarkers": true, + "mapProvider": "OpenStreetMap", + "mapboxAccessToken": "", + "customLayers": [ + { + "name": "street", + "url": "" + } + ] + }, + "RandomPhoto": { + "enabled": true + }, + "Other": { + "enableCache": true, + "enableOnScrollRendering": true, + "defaultPhotoSortingMethod": "ascDate", + "enableOnScrollThumbnailPrioritising": true, + "NavBar": { + "showItemCount": true + }, + "captionFirstNaming": false + }, + "authenticationRequired": true, + "unAuthenticatedUserRole": "Admin", + "Media": { + "Thumbnail": { + "iconSize": 45, + "personThumbnailSize": 200, + "thumbnailSizes": [ + 240, + 480 + ] + }, + "Video": { + "enabled": true + }, + "Photo": { + "Converting": { + "enabled": true + } + } + }, + "MetaFile": { + "enabled": true + }, + "Faces": { + "enabled": true, + "keywordsToPersons": true, + "writeAccessMinRole": "Admin" + } + } +}``` \ No newline at end of file diff --git a/README.md b/README.md index 5e410b3c..b2480d9d 100644 --- a/README.md +++ b/README.md @@ -96,10 +96,11 @@ You can set up the app the following ways: * Through switches * Like: `node start -- --Server-port=3000 --Client-authenticationRequired=false` * You can check the generated `config.json` for the config hierarchy - * Note: you can run the app to generate the config file only, by running `npm start -- --config-only` * Through environmental variable * like set env. variable `Server-port` to `3000` +Full list of configuration options are available at the [MANPAGE.md](MANPAGE.md). + ### 1.4 Useful links/tips: #### using nginx diff --git a/docker/README.md b/docker/README.md index cb1954b8..e657e04a 100644 --- a/docker/README.md +++ b/docker/README.md @@ -62,6 +62,7 @@ docker-compose up -d `-d` runs it as a daemon. Remove it, so you will see the logs. After the containers are up and running, you go to `yourdomain.com` and log in with user: `admin` pass: `admin` and set up the page in the settings. +Full list of configuration options are available at the [MANPAGE.md](../MANPAGE.md). **Note:** `docker-compose.yml` contains `restart:always`, so the containers will be automatically started after reboot ([read more here](https://stackoverflow.com/questions/43671482/how-to-run-docker-compose-up-d-at-system-start-up)). diff --git a/gulpfile.ts b/gulpfile.ts index 69a8d252..c2e88c63 100644 --- a/gulpfile.ts +++ b/gulpfile.ts @@ -10,7 +10,7 @@ import * as child_process from 'child_process'; // @ts-ignore import * as jeditor from 'gulp-json-editor'; import {XLIFF} from 'xlf-google-translate'; -import {Config} from './src/common/config/private/Config'; +import {Config, PrivateConfigClass} from './src/common/config/private/Config'; import {ConfigClassBuilder} from 'typeconfig/src/decorators/builders/ConfigClassBuilder'; const execPr = util.promisify(child_process.exec); @@ -345,10 +345,14 @@ gulp.task('add-translation-only', (cb) => { }); gulp.task('generate-man', async (cb) => { + const defCFG = ConfigClassBuilder.attachInterface(new PrivateConfigClass()); + defCFG.Server.sessionSecret = []; let txt = '# Pigallery 2 man page\n'; txt += 'pigallery2 uses [typeconfig](https://github.com/bpatrik/typeconfig) for configuration\n\n'; txt += '`npm start -- --help` prints the following:\n\n'; - txt += '```\n' + ConfigClassBuilder.attachPrivateInterface(Config).__printMan() + '```'; + txt += '```\n' + ConfigClassBuilder.attachPrivateInterface(defCFG).__printMan() + '```'; + txt += '\n\n ### `config.json` sample:\n'; + txt += '```json\n' + JSON.stringify(defCFG, null, 4) + '```'; await fsp.writeFile('MANPAGE.md', txt); cb(); }); diff --git a/src/common/config/private/Config.ts b/src/common/config/private/Config.ts index dbfe7a61..210897bb 100644 --- a/src/common/config/private/Config.ts +++ b/src/common/config/private/Config.ts @@ -29,9 +29,9 @@ import {ConfigProperty, IConfigClass} from 'typeconfig/common'; } }) export class PrivateConfigClass implements IPrivateConfig { - @ConfigProperty() + @ConfigProperty({type: ServerConfig.Config}) Server: ServerConfig.Config = new ServerConfig.Config(); - @ConfigProperty() + @ConfigProperty({type: ClientConfig.Config}) Client: IConfigClass & ClientConfig.Config = (new ClientConfig.Config()); constructor() {