photofloat/README.md

256 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# subPhotoFloat A [Photofloat](https://git.zx2c4.com/PhotoFloat/) fork
## Web Photo Gallery via Static JSON & Dynamic Javascript with a Python Backend
by Jason A. Donenfeld (<Jason@zx2c4.com>)
with some changes by Markus Pawlata (<markus@derdritte.net>) and other [collaborators](https://git.jocke.no/photofloat/log/?h=patches).
![Screenshot](https://photos.derdritte.net/img/screenshot.png)
subPhotoFloat is an open source web photo gallery aimed at sleekness and speed. It keeps with a minimalist philosophy, preferring to work over directory structures rather than bloated photo database management software (there are good options available for that, if you want it). Everything it generates is static, which means it's extremely fast.
[Check out a demo!](https://photos.derdritte.net/#!/random)
## How It Works
subPhotoFloat consists of two main segments a Python script and a JavaScript application.
The Python script scans a directory tree of images, whereby each directory constitutes an album. It then populates a second folder, known as the cache folder with statically generated JSON files and thumbnails. The scanner extracts metadata from EXIF tags in JPEG photos. subPhotoFloat is smart about file and directory modification time, so you are free to run the scanner script as many times as you want, and it will be very fast if there are few or zero changes since the last time you ran it.
Also a part of the Python script is a small flask webapp which allows you to have authentication for certain albums/images and can start the scanner.
The JavaScript application consists of a single `index.html` file with a single `scripts.min.js` and a single `styles.min.css`. It fetches the statically generated JSON files and thumbnails on the fly from the `cache` folder to create a speedy interface. Features include:
* Separate album view and photo view
* Album metadata pre-fetching
* Photo pre-loading
* Smooth up and down scaling
* Mouse-wheel support
* Swipe support (on mobile)
* Metadata display
* Consistent hash url format
* Linkable states via ajax urls
* Link to original images (can be turned off)
* Optional Google Analytics integration
* Optional server-side authentication support
* A thousand other tweaks here and there...
It is, essentially, a very slick and fast, fairly minimal but still well-featured photo gallery app.
## Dependencies
* python >= 2.6
* pillow >= 5.3.0
* nginx (or any webserver, really)
### Optional
* flask >= 0.11 (for authentication)
* flask-login >= 0.4.1 (for authentication)
* virtualenv (this is nice, [believe me](https://docs.python-guide.org/dev/virtualenvs/#lower-level-virtualenv))
* ffmpeg (for video conversion)
## Installation
### Download the source code from the git repository
$ git clone https://derdritte.net/gitea/markus/photofloat
$ cd photofloat
### Change or delete the Google Analytics ID tracker
To delete:
$ rm web/js/999-googletracker.js
To change:
$ vim web/js/999-googletracker.js
Modify the part that says UA-XXXXXX-X and put your own in there.
### Tweak the index.html page to have a custom title or copyright notice
$ vim web/index.html
### Build the web page
This simply runs all the javascript through Google Closure Compiler and all the CSS through YUI Compressor to minify and concatenate everything. Be sure you have java installed.
$ cd web
$ make
### Generate the albums
Now that we're in the web directory, let's make a folder for cache and a folder for the pictures:
$ mkdir albums
$ mkdir cache
When you're done, fill albums with photos and directories of photos. You can also use symlinks. Run the static generator (you need Python≥2.6 and the Python Imaging Library):
$ cd ../scanner
$ ./main.py ../web/albums ../web/cache
After it finishes, you will be all set. Simply have your web server serve pages out of your web directory. You may want to do the scanning step in a cronjob, if you don't use the deployment makefiles mentioned below.
### Nginx configuration for static-only
Please keep in mind this will not provide any kind of access-restrictions.
server {
listen 80;
server_name photos.jasondonenfeld.com;
location / {
index index.html;
root /var/www/htdocs/photos.jasondonenfeld.com;
}
}
Now after deploying `/var/www/htdocs/photos.jasondonenfeld.com` should contain:
* index.html
* js/
* css/
* img/
* albums/
* cache/
You can easily manage that by creating a folder structure and copying relevant files over:
$ cd ..
photofloat ~ $ mkdir <deployment-folder>/js <deployment-folder>/css
$ cp web/js/scripts.min.js <deployment-folder>/js
$ cp web/css/styles.min.css <deployment-folder>/css
$ cp -a fonts img index.html <deployment-folder>/
For easy updates `albums` and `cache` can be set to also live in \<deployment-folder>, this is especially recommended if you are using the optional flask app mentioned in the following section.
Do **not** keep any of your config or python-files where the webserver can read or write to, the `deployment-config.mk` is most sensitive. If you only want the static html/json & javascript application you are done now!
## Optional: Server-side Authentication using flask
The JavaScript application uses a very simple API to determine if a photo can be viewed or not. If a JSON file returns error `403`, the album is hidden from view. To authenticate, `POST` a username and a password to `/auth`. If unsuccessful, `403` is returned. If successful, `200` is returned, and the previously denied json files may now be requested. If an unauthorized album is directly requested in a URL when the page loads, an authentication box is shown.
subPhotoFloat ships with an optional server side component called FloatApp to facilitate this, which lives in `scanner/floatapp`. It is a simple Flask-based Python web application.
### Installation
We need to install flask and other dependencies, ideally in a virtualenv, as this will keep your system-wide python installation clean and you can easily install more packages or different versions.
$ cd scanner
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
### Edit the app.cfg configuration file
$ vim floatapp/app.cfg
Give this file a correct username and password for an admin, as well as a secret token. The admin user is allowed to call `/scan`, which automatically runs the scanner script mentioned in the previous section.
In `app.cfg` you may also add elements to the `PERMISSION_MAP` as follows. The dictionary takes any path (to either an album or an image) and restricts any album or image matching that path to the listed tokens.
PERMISSION_MAP = {
'private': ['thisisatoken'],
'alsoprivate/butonlythis.jpg': ['morethan', 'onetoken'],
}
Tokens can contain anything you wish and you can add as many paths and tokes as you require. One match in the `PERMISSION_MAP` will allow access even if another rule would forbid it. The admin is allowed to see any album or image.
### Configure nginx
FloatApp makes use of `X-Accel-Buffering` and [X-Accel-Redirect](https://www.nginx.com/resources/wiki/start/topics/examples/x-accel/) to force the server-side component to have minimal overhead when serving images via flask. Here is an example nginx configuration that can be tweaked:
server {
listen 80;
server_name photos.jasondonenfeld.com;
location / {
index index.html;
root /var/www/htdocs/photos.jasondonenfeld.com;
}
include uwsgi_params;
location /albums/ {
uwsgi_pass unix:/var/run/uwsgi-apps/photofloat.socket;
}
location /cache/ {
uwsgi_pass unix:/var/run/uwsgi-apps/photofloat.socket;
}
location /scan {
uwsgi_pass unix:/var/run/uwsgi-apps/photofloat.socket;
}
location /auth {
uwsgi_pass unix:/var/run/uwsgi-apps/photofloat.socket;
}
location /photos {
uwsgi_pass unix:/var/run/uwsgi-apps/photofloat.socket;
}
location /internal-cache/ {
internal;
alias /var/www/uwsgi/photofloat/cache/;
}
location /internal-albums/ {
internal;
alias /var/www/uwsgi/photofloat/albums/;
}
}
Note that the `internal-*` paths must match that of `app.cfg`, since the flask app will redirect the "external" `/albums` and `/cache` paths to internal ones set in that config.
### Configure uwsgi (or use an alternate wsgi-provider)
$ cat /etc/uwsgi.d/photofloat.ini
[uwsgi]
chdir = /var/www/uwsgi/%n
master = true
uid = %n
gid = %n
chmod-socket = 660
chown-socket = nginx:nginx
socket = /var/run/uwsgi-apps/%n.socket
logto = /var/log/uwsgi/%n.log
virtualenv = /var/www/uwsgi/photofloat/scanner/venv
processes = 4
idle = 1800
die-on-idle = true
plugins = python27
module = floatapp:app
Change the paths for chdir, socket, logto and virtualenv to your preference.
Naturally, you can use any of the options available to [deploy](http://flask.pocoo.org/docs/1.0/deploying/#self-hosted-options) the flask app.
## Optional: Deployment Makefiles
Both the scanner and the webpage have a `make deploy` target, and the scanner has a `make scan` target, to automatically deploy assets to a remote server and run the scanner. For use, customize `deployment-config.mk` in the root of the project, and carefully read the `Makefile`s to learn what's happening.
Be aware: you will very likely have to adapt the deploy-instructions to what you have deployed on your server.
If you are using the flask-app you will most likely not need the Makefiles.
## Mailing List & Suggestions
If you have any suggestions, feel free to contact the subPhotoFloat community via [our mailing list](http://lists.zx2c4.com/mailman/listinfo/photofloat). We're open to adding all sorts of features and working on integration points with other pieces of software.
Note: As the project is 8+ years old, the mailing list has slowed down a bit, if you do not get an answer immediately, please be patient and give other users some time to respond.
This app is also fairly small, so this might be the perfect project to try and add some small features yourself. For reference you may want to look at the flask & nginx documentation.
## License
Copyright (C) 2010 - 2014 Jason A. Donenfeld. All Rights Reserved.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.