myks-gallery 0.8

Architecture

myks-gallery requires two storage areas:

• The first one contains the original photos. It’s a read-only reference. You can upload photos there with aws s3 sync, gsutil rsync, rsync, etc. depending on the platform.

• The second one contains downscaled photos and ZIP archives of album exports. It’s a cache. You can set up expiry policies and clear it without affecting the gallery, aside from the cost of rescaling images again.

myks-gallery accesses them through Django’s file storage API, meaning that you can use any storage for which a Django storage backend exists. You should use a third-party storage backend if you’re storing files in a cloud service and Djang’s built-in FileSystemStorage if you’re storing them locally on the filesystem, typically for local development.

Installation guide

This application isn’t exactly plug’n’play. There are many moving pieces. Here’s the general process for integrating myks-gallery into an existing website:

1. Download and install the package from PyPI:

   $ pip install myks-gallery

2. Add gallery.apps.GalleryConfig to INSTALLED_APPS:

   INSTALLED_APPS += ['gallery.apps.GalleryConfig']

3. Configure the settings — see below for the list.

4. Add the application to your URLconf with the gallery application namespace:

   urlpatterns += [
       path('gallery/', include('gallery.urls', namespace='gallery')),
   ]

5. Create a suitable base.html template. It must provide three blocks: title, extrahead, content, as shown in this example.

6. Optionally, if you’re serving files from the local filesystem, enable X-accel (nginx) or mod_xsendfile (Apache) for your photo and cache directories.

7. Scan your photos with the “Scan photos” button in the admin or the scanphotos management command and define access policies.

The source contains a sample application in the example directory. It can help you see how everything fits together. See below for how to run it.

Access control

myks-gallery provides two levels of access control: by album and by photo.

By default, albums and photos aren’t visible by anyone, except users with the “Can see all photos” permission, including superusers who have it implicitly.

To make them visible, you must define an access policy. You have two options: public access or access restricted to select users or groups.

Access policies for albums are configured explicitly in the admin.

In most cases, you will enable the “Photos inherit album access policy” option, so that the access policy also applies to all photos in the album.

Access policies for photos may also be configured for granular control.

For example, if you want to publish just a few photos in an album, make these photos public, make the album public, but don’t enable “Photos inherit album access policy”. Other photos in the album won’t be visible.

Another example, if you want to share an album privately except for a few photos, set an empty access policy on these photos (e.g. by adding then removing yourself), then allow some groups or users to view the album.

Permissions

myks-gallery defines two permissions for django.contrib.auth:

• “Can scan the photos directory” allows using the “Scan photos” button in the admin.

• “Can see all photos” allows seeing all albums and all photos regardless of access policies.

Settings

GALLERY_PATTERNS = (
    ('Photos',
        r'(?P<a_year>\d{4})/(?P<a_month>\d{2})_(?P<a_day>\d{2})_'
        r'(?P<a_name>[^_/]+)/'
        r'(?P<p_year>\d{4})-(?P<p_month>\d{2})-(?P<p_day>\d{2})_'
        r'(?P<p_hour>\d{2})-(?P<p_minute>\d{2})-(?P<p_second>\d{2})\.jpg'),
)

GALLERY_RESIZE_PRESETS = {
    'thumb': (128, 128, True),
    'standard': (768, 768, False),
}

GALLERY_RESIZE_OPTIONS = {
    'JPEG': {'quality': 95, 'optimize': True},
}

0.9

Under development

0.8

• Changed photo access policies to always override album access policies, even when “Photos inherit album access policy” is enabled. This makes it possible to restrict access with photo access policies, rather than just extend it.

• Updated for Django 3.0.

0.7

• Updated for Django 2.0.

0.6

• Added migrations for compatibility with Django 1.9.

To upgrade an existing project, run: django-admin migrate --fake-initial.

0.5

This version uses the Django file storage API for all operations on files, making it possible to use services such as Amazon S3 or Google Cloud Storage for storing photos and thumbnails. It introduces the GALLERY_PHOTO_STORAGE and GALLERY_CACHE_STORAGE settings. They supersede GALLERY_PHOTO_DIR and GALLERY_CACHE_DIR.

When upgrading to 0.5 or later, you should clear the cache directory. Previously cached thumbnails and exports won’t be used by this version.

It also include some smaller changes.

• Switched ordering of albums to always show the most recent albums first.

• Allowed customizing the number of photos in album previews.

• Preserved original order of photos in album previews.

• Added pagination on album preview pages.

• Changed the hashing schema. This invalides the cache. You should clear it.

• Fixed collision between zip archives containing photos with the same name.

0.4

• Provided exports of albums as zip archives.

• Fixed preview of photos affected by batch access policy changes.

0.3

• Support for Python 3 and Django 1.6.

• Hid public albums by default for logged-in users.

• Switched the default styles to a responsive design.

• Added an option to scanphotos to precompute thumbnails.

• Added an option to scanphotos to resynchronize photo dates.

• Fixed bugs in photo dates.

0.2

• Made most settings optional for easier deployment.

• Made “sendfile” optional and used streaming responses as a fallback.

• Worked around a crash in libjpeg when creating large JPEG previews.

• Added many tests.

0.1

• Initial public release, with the history from my private repository.

• Added documentation (README file).

• Added a sample application.