1
0
mirror of https://github.com/bpatrik/pigallery2.git synced 2024-12-12 11:15:22 +02:00
pigallery2/README.md

226 lines
10 KiB
Markdown
Raw Normal View History

2018-12-03 23:38:25 +02:00
# PiGallery2
2020-01-02 23:28:18 +02:00
![GitHub package.json version](https://img.shields.io/github/package-json/v/bpatrik/pigallery2)
2020-01-02 23:11:59 +02:00
[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/bpatrik/pigallery2.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/bpatrik/pigallery2/context:javascript)
2017-07-03 19:17:49 +02:00
[![Build Status](https://travis-ci.org/bpatrik/pigallery2.svg?branch=master)](https://travis-ci.org/bpatrik/pigallery2)
2020-01-02 23:28:18 +02:00
[![Coverage Status](https://coveralls.io/repos/github/bpatrik/pigallery2/badge.svg?branch=master)](https://coveralls.io/github/bpatrik/pigallery2?branch=master)
2016-05-02 10:07:42 +02:00
[![Heroku](https://heroku-badge.herokuapp.com/?app=pigallery2&style=flat)](https://pigallery2.herokuapp.com)
2019-12-24 00:17:05 +02:00
[![Docker build](https://github.com/bpatrik/pigallery2/workflows/docker-buildx/badge.svg)](https://github.com/bpatrik/pigallery2/actions)
2018-11-30 16:36:42 +02:00
[![dependencies Status](https://david-dm.org/bpatrik/pigallery2/status.svg)](https://david-dm.org/bpatrik/pigallery2)
2020-01-02 23:28:18 +02:00
2018-12-03 23:38:25 +02:00
Homepage: http://bpatrik.github.io/pigallery2/
2017-03-22 20:38:39 +02:00
This is a directory-first photo gallery website, optimised for running on low resource servers (especially on raspberry pi)
2016-03-14 14:30:15 +02:00
2017-06-04 15:25:22 +02:00
## Live Demo
2019-01-02 22:22:03 +02:00
Live Demo @ heroku: https://pigallery2.herokuapp.com/
2018-12-02 23:30:49 +02:00
- the demo page **first load** might take up **30s**: the time while the free webservice boots up
2017-03-22 20:38:39 +02:00
2019-12-12 18:22:41 +02:00
![PiGallery2 - Animated gif demo](docs/demo.gif)
2018-05-16 02:01:11 +02:00
## Table of contents
2020-01-01 23:25:45 +02:00
1. [Getting started](#1-getting-started-also-works-on-raspberry-pi)
2018-12-22 01:29:05 +02:00
2. [Translate the page to your own language](#2-translate-the-page-to-your-own-language)
3. [Feature list](#3-feature-list)
2019-02-25 12:50:27 +02:00
4. [Suggest/endorse new features](#4-suggestendorse-new-features)
2019-02-25 12:41:56 +02:00
5. [Known errors](#5-known-errors)
6. [Credits](#6-credits)
2016-03-14 14:30:15 +02:00
2017-03-22 20:38:39 +02:00
2018-05-16 02:01:11 +02:00
## 1. Getting started (also works on Raspberry Pi)
2020-01-01 23:25:45 +02:00
### 1.1 Install and Run with Docker (recommended)
[Docker](https://www.docker.com/) with [docker-compose](https://docs.docker.com/compose/) is the offitial and recommend way of installing and running *Pigallery2*.
It contains all necessary dependencies, auto restarts on reboot, supports https, easy to upgrade to newer versions.
For configuration and docker-compose files read more [here](docker/README.md) or check all builds: https://hub.docker.com/r/bpatrik/pigallery2/tags/
2020-01-01 23:25:45 +02:00
### 1.2 Direct Install (if you are familiar with nodejs and building npm packages from source)
2019-12-29 11:45:01 +02:00
As an alternative, you can also directly install nodejs and the app and run it natively.
### 1.2.0 [Install NodeJs](https://nodejs.org/en/download/)
2017-06-04 15:25:22 +02:00
Download and extract
```bash
curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
2018-12-02 23:15:39 +02:00
sudo apt-get install -y nodejs
2017-06-04 15:25:22 +02:00
```
2018-12-02 23:15:39 +02:00
2018-12-06 10:52:04 +02:00
Full node install on raspberry pi description: https://www.w3schools.com/nodejs/nodejs_raspberrypi.asp
2017-06-04 15:25:22 +02:00
### 1.2.1 Install PiGallery2
#### 1.2.1-a Install from release
2017-07-12 18:35:23 +02:00
2017-06-04 15:25:22 +02:00
```bash
cd ~
2019-12-30 22:49:50 +02:00
wget https://github.com/bpatrik/pigallery2/releases/download/1.8.0/pigallery2.zip
2019-01-26 22:00:01 +02:00
unzip pigallery2.zip -d pigallery2
2018-05-16 02:01:11 +02:00
cd pigallery2
2017-07-12 18:35:23 +02:00
npm install
```
#### 1.2.1-b Install from source
2020-01-01 22:18:35 +02:00
**Note:** A build requires a machine with around 2GB or memory.
2020-01-01 23:25:45 +02:00
2017-07-12 18:35:23 +02:00
```bash
cd ~
wget https://github.com/bpatrik/pigallery2/archive/master.zip
unzip master.zip
2018-05-16 02:01:11 +02:00
cd pigallery2-master # enter the unzipped directory
2017-06-04 15:25:22 +02:00
npm install
2020-01-01 19:29:44 +02:00
npm run build
2017-06-04 15:25:22 +02:00
```
2020-01-01 23:25:45 +02:00
**Note**: It is recommended to create a release version with `npm run create-release` on a more powerful mashine and deploy that to you server.
**Note**: you can use `npm run create-release -- --languages=fr,ro` to restrict building to the listed languages (english is added by default)
2017-07-12 18:35:23 +02:00
#### 1.2.2 Run PiGallery2
2017-06-04 15:25:22 +02:00
```bash
npm start
```
2018-12-05 22:55:11 +02:00
To configure it, run `PiGallery2` first to create `config.json` file, then edit it and restart.
The app has a nice UI for settings, you may use that too.
2017-07-25 23:39:50 +02:00
Default user: `admin` pass: `admin`
2017-06-04 15:25:22 +02:00
**Note**: First run, you might have file access issues and port 80 issue, see [#115](https://github.com/bpatrik/pigallery2/issues/115).
2019-12-29 11:45:01 +02:00
Running `npm start -- --Server-port=8080` will start the app on port 8080 that does not require `root`
Adding read/write permissions to all files can solve the file access issue `chmod -R o-w .`, see [#98](https://github.com/bpatrik/pigallery2/issues/98).
### 1.3 Advanced configuration
You can set up the app the following ways:
* Using the UI
* Manually editing the `config.json`
* Through switches
2019-12-12 12:04:20 +02:00
* Like: `node start -- --Server-port=3000 --Client-authenticationRequired=false`
* You can check the generated `config.json` for the config hierarchy
* Through environmental variable
* like set env. variable `Server-port` to `3000`
2020-02-07 14:59:36 +02:00
Full list of configuration options are available at the [MANPAGE.md](MANPAGE.md).
### 1.4 Useful links/tips:
2018-05-16 02:01:11 +02:00
#### using nginx
It is recommended to use a reverse proxy like nginx before node
2017-07-29 23:39:06 +02:00
https://stackoverflow.com/questions/5009324/node-js-nginx-what-now
2017-10-19 18:08:07 +02:00
2018-05-16 02:01:11 +02:00
#### making https
With cerbot & nginx it is simple to set up secure connection. You have no excuse not doing so.
2017-07-29 23:39:06 +02:00
https://certbot.eff.org/
2018-05-16 02:01:11 +02:00
#### node install error:
2017-10-19 18:08:07 +02:00
If you get error during module installation, make sure you have everything to build node modules from source
```bash
apt-get install build-essential libkrb5-dev gcc g++
```
2018-12-06 10:52:04 +02:00
## 2. Translate the page to your own language
1. [Install Pigallery2](#121-b-install-from-source) from source (with the release it won't work)
2018-05-16 02:01:11 +02:00
2. add your language e.g: fr
```bash
npm run add-translation -- --fr
```
2019-12-12 12:04:20 +02:00
it creates a new `messages.fr.xls` file at `src/frontend/translate` folder,
2018-05-16 02:01:11 +02:00
it will already contain dummy translation with google translate.
3. 'fix' the dummy translation
4. test if it works:
build and start the app
```bash
npm install
2020-01-01 23:28:09 +02:00
npm run build
2018-05-16 02:01:11 +02:00
npm start
```
2018-12-22 01:20:03 +02:00
5. (optional) create a pull request at github to add your translation to the project.
2020-01-01 23:28:09 +02:00
**Note**: you can also build your own release with as described in [1.1.1-b Install from source](#121-b-install-from-source);
2018-05-16 02:01:11 +02:00
2018-12-06 10:52:04 +02:00
## 3. Feature list
2017-06-04 15:25:22 +02:00
2020-01-01 23:25:45 +02:00
* supported formats [full list here](https://github.com/bpatrik/pigallery2/blob/master/src/common/SupportedFormats.ts):
2019-01-12 19:08:34 +02:00
* images: **jpg, jpeg, jpe, webp, png, gif, svg**
* videos: **mp4, ogg, ogv, webm**
2020-01-01 23:25:45 +02:00
* with (built-in) transcoding: avi, mkv, mov, wmv, flv, mts, m2ts, mpg, 3gp, m4v, mpeg, vob, divx, xvid, ts
2017-03-22 20:38:39 +02:00
* **Rendering directories as it is**
* Listing subdirectories recursively
* Listing photos in a nice grid layout
* showing **tag/keywords, locations, GPS coordinates** for photos
* rendering photos on demand (on scroll)
2017-03-22 20:41:32 +02:00
* **On the fly thumbnail generation** in several sizes
2017-03-22 20:38:39 +02:00
* prioritizes thumbnail generation (generating thumbnail first for the visible photos)
* saving generated thumbnails to TEMP folder for reuse
2018-12-05 22:55:11 +02:00
* supporting multi-core CPUs
2020-01-01 23:28:09 +02:00
* supporting hardware acceleration ([sharp](https://github.com/lovell/sharp))
* Custom lightbox for full screen photo and video viewing
2017-07-09 12:03:17 +02:00
* keyboard support for navigation
2017-03-22 20:38:39 +02:00
* showing low-res thumbnail while full image loads
* Information panel for showing **Exif info**
2017-07-11 22:23:07 +02:00
* Automatic playing
2017-07-17 18:30:16 +02:00
* gesture support (swipe left, right, up)
* shortcut support
2020-01-01 23:25:45 +02:00
* On the fly photo downscaling for faster load [#50](https://github.com/bpatrik/pigallery2/issues/50)
* on zoom, the original photo loads
2017-03-22 20:41:32 +02:00
* Client side caching (directories and search results)
* Rendering **photos** with GPS coordinates **on open street maps**
* .gpx file support: rendering paths to map
* supports [OSM](https://www.openstreetmap.org) and [Mapbox](https://www.mapbox.com) by default, but you can add any provider that has a tile url
2017-03-22 20:41:32 +02:00
* **Two modes: SQL database and no-database mode**
* both modes supports
* user management
* password protection can be disabled/enabled
2017-03-22 20:38:39 +02:00
* database mode supports:
* faster directory listing
* searching
* instant search, auto complete
2017-07-09 12:03:17 +02:00
* sharing
2017-03-22 20:38:39 +02:00
* setting link expiration time
2019-07-21 17:00:07 +02:00
* Faces (persons) support
* reads Adobe's XMP Face region metadata. (It is defined by the Metadata Working Group (MWG).)
* shows face bounding box over images
2018-03-30 02:30:23 +02:00
* internalization / translation support
2020-01-01 23:25:45 +02:00
* currently supported languages: eng, hun, ro, ru, fr
2017-07-29 23:39:06 +02:00
* Nice design
2017-03-22 20:38:39 +02:00
* responsive design (phone, tablet desktop support)
2017-07-29 23:39:06 +02:00
* Setup page
2018-11-02 11:51:36 +02:00
* Random photo url
* You can generate an url that returns a random photo from your gallery. You can use this feature to develop 3rd party applications, like: changing desktop background
2020-01-01 23:25:45 +02:00
* duplicate photo detection
2018-11-22 20:12:10 +02:00
* video support
2020-01-01 23:25:45 +02:00
* fully supports `*.mp4` files and partially (might have errors with safari and IE) supports `*.ogg`, `*.ogv`, `*.webm` files
* uses ffmpeg and ffprobe to generate video thumbnails
2020-01-01 23:25:45 +02:00
* can transcode videos to mp4 for better support
* job sceduling support, with the following supported task: [#92](https://github.com/bpatrik/pigallery2/issues/92)
* converting/transcoding videos [#66](https://github.com/bpatrik/pigallery2/issues/66) [#71](https://github.com/bpatrik/pigallery2/issues/71)
* generating thumbnails
* generating converted photos
* cleaning up temp folder
* indexing db
* folder ignoring [#87](https://github.com/bpatrik/pigallery2/issues/87)
2018-12-06 10:52:04 +02:00
* Dockerized
2017-07-09 12:03:17 +02:00
* **Markdown based blogging support** - `future plan`
2017-03-22 20:41:32 +02:00
* you can write some note in the blog.md for every directory
2017-03-22 20:38:39 +02:00
* bug free :) - `In progress`
2019-02-25 12:41:56 +02:00
2019-02-25 12:49:37 +02:00
## 4. Suggest/endorse new features
You are welcome to suggest new features to the application via [github issues](https://github.com/bpatrik/pigallery2/issues).
2019-02-25 12:41:56 +02:00
I cannot garantie any dealine with the development of a new feature. (I usually fix bugs within week/weeks.)
I will give a higher priority to a feature that has more 'likes' (i.e.: `+1`-s or thumbs ups) on it.
2018-03-30 02:30:23 +02:00
2019-02-25 12:41:56 +02:00
## 5. Known errors
2018-11-02 11:51:36 +02:00
* EXIF orientation tag:
* Some photos code the orientation tag and with/height in a less conventional format, like the "duck photo" in [#19](https://github.com/bpatrik/pigallery2/issues/19).
After Browsers support orientation tag natively [#172](https://github.com/bpatrik/pigallery2/issues/172), I could not find a solution for that.
2018-12-02 21:57:16 +02:00
* Video support on weak servers (like raspberry pi) with low upload rate
2020-01-01 23:25:45 +02:00
* video playback may use up too much resources and the server might not response for a while. Enable video transcoding in the app, to transcode the videos to lover bitrate.
2019-02-25 12:41:56 +02:00
## 6. Credits
2018-05-16 02:01:11 +02:00
Crossbrowser testing sponsored by [Browser Stack](https://www.browserstack.com)
[<img src="https://camo.githubusercontent.com/a7b268f2785656ab3ca7b1cbb1633ee5affceb8f/68747470733a2f2f64677a6f7139623561736a67312e636c6f756466726f6e742e6e65742f70726f64756374696f6e2f696d616765732f6c61796f75742f6c6f676f2d6865616465722e706e67" alt="Browser Stack" height="31px" style="background: cornflowerblue;">](https://www.browserstack.com)
2018-03-30 02:30:23 +02:00