pycbox 0.0.3

Web interface for directory listings and picture gallery

Simple web interface showing a directory-listing or thumbnail-gallery of the files or images in the files/ subdirectory. Users can upload files if the folder has write-permissions for all.

An example can be seen at pix.coldfix.eu.

This repo is a python rewrite of the picbox php app.

Usage

You can quickly install the latest release and locally serve files from your ~/Pictures directory as follows:

pip install pycbox --user
pycbox -w ~/Pictures

In order to allow network access on all network interfaces you also need to add the --host 0.0.0.0 option, e.g.:

pycbox -w ~/Pictures -h 0.0.0.0

Alternatively, you can run pycbox without installation from the git checkout. Though in this case, you still need to install the dependencies as follows:

pip install -r requirements.txt --user
./bin/pycbox -w ~/Pictures

However, running the pycbox from the command line like this is not recommended for deployment! From the flask documentation:

While lightweight and easy to use, Flask’s built-in server is not suitable for production as it doesn’t scale well and by default serves only one request at a time. Some of the options available for properly running Flask in production are documented here.

A more sophisticated server can e.g. be run using twisted:

twistd --nodaemon --logfile=- web --port=tcp:5000 --wsgi=pycbox.app

In fact, the recommended method is using docker, see Deployment.

Config

If it exists, config.yml will be loaded from the active directory. The config file may become mandatory, so you should always copy and adjust the shipped example config:

cp config.example.yml config.yml

An alternate config file name or path can be specified via the PYCBOX_CONFIG environment variable, i.e. like this:

PYCBOX_CONFIG=/path/to/alt_config.yml python pycbox.py
PYCBOX_CONFIG=/path/to/alt_config.yml twistd web --wsgi=pycbox.app

Deployment

The recommended method is to run pycbox is via docker. The image can be built and run as follows:

docker build . -t pycbox
docker run --cap-drop=all \
    -v `pwd`/files:/pycbox/files \
    -p 5000:5000 \
    --name=pycbox pycbox

or simply:

docker-compose up

Add -d to either command line to run in the background.

Proxy

In order to run the application on a subdomain, you will need to setup a proxy forward. Example nginx configuration to show the site on pix subdomain:

server {
    listen      80;
    listen [::]:80;
    server_name pix.example.com pix.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen      443 ssl;
    listen [::]:443 ssl;
    server_name pix.example.com pix.example.org;
    access_log /var/log/nginx/access_pics.log;
    location / {
        proxy_pass                          http://localhost:5000;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header Host               $host;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade            $http_upgrade;
        proxy_set_header Connection         upgrade;
    }
}

Upload

To enable uploading to a particular subfolder, make it writable by all:

mkdir -p files/public
chmod 777 files/public

Debug mode

DO NOT DO THIS IN PRODUCTION since it allows the client to execute arbitrary code.

To run the application in debug mode on port 5000, type either:

python pycbox.py --debug

or (recommended):

FLASK_APP=pycbox.py FLASK_DEBUG=1 flask run

The second command takes care of reloading the server when the python module is changed and is therefore recommended for development.

Big TODOs

• use redis for caching thumbs and highlighted files

• use asciidoc for markdown

• use pygments for highlighting

• configure via YAML file: auth, quota, uploads, deny globs

Changes

0.0.3

Date: 06.09.2017

• fix startup error in debug mode, due to port being a string

• fix startup error in docker container, due to permissions

• fix error when trying to upload into root folder

• fix permission problems in docker container

0.0.2

Date: 11.08.2017

• fix install package (if installing using pip)

0.0.1

Date: 10.08.2017

Features include:

• directory index

• thumbnail gallery

• highlighting (source-highlight or highlight)

• cache thumbnails and highlights relative to current folder

• configurable root folder

• dockerfile