Installation & configuration

Installation

The easiest way to install Photologue is with pip; this will give you the latest version available on PyPi:

pip install django-photologue

You can also take risks and install the latest code directly from the Github repository:

pip install -e git+https://github.com/jdriscoll/django-photologue.git#egg=django-photologue

This code should work ok - like Django itself, we try to keep the master branch bug-free. However, we strongly recommend that you stick with a release from the PyPi repository, unless if you’re confident in your abilities to fix any potential bugs on your own!

Python 3

Photologue works with Python 3 (3.3 or later).

Dependencies

3 apps that will be installed automatically if required.

And 1 dependency that you will have to manage yourself:

Note

Photologue tries to support the same Django version as are supported by the Django project itself.

That troublesome Pillow…

Pillow can be tricky to install; sometimes it will install smoothly out of the box, sometimes you can spend hours figuring it out - installation issues vary from platform to platform, and from one OS release to the next, so listing them all here would not be realistic. Google is your friend, and it’s worth noting that Pillow is a fork of PIL, so googling ‘PIL installation <your platform>’ can also help.

  1. You should not have installed both PIL and Pillow; this can cause strange bugs. Please uninstall PIL before you install Pillow.

  2. In some situations, you might not be able to use Pillow at all (e.g. if another package has a dependency on PIL). Photologue has a clumsy answer for this: write a temporary file /tmp/PHOTOLOGUE_NO_PILLOW, then install Photologue. This will tell Photologue to install without Pillow. It should work, but it hasn’t been tested!

  3. Sometimes Pillow will install… but is not actually installed. This ‘undocumented feature’ has been reported by a user on Windows. If you can’t get Photologue to display any images, check that you can actually import Pillow:

    $ python manage.py shell
    Python 3.3.1 (default, Sep 25 2013, 19:29:01)
    [GCC 4.7.3] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    (InteractiveConsole)
    >>> from PIL import Image
    >>>
    

Configure Your Django Settings file

  1. Add to your INSTALLED_APPS setting:

    INSTALLED_APPS = (
         # ...other installed applications...
         'photologue',
         'sortedm2m',
    )
    
  2. Confirm that your MEDIA_ROOT and MEDIA_URL settings are correct (Photologue will store uploaded files in a folder called ‘photologue’ under your MEDIA_ROOT).

  3. Enable the admin app if you have not already done so.

  4. Enable the Django sites framework if you have not already done so. This is not enabled by default in Django, but is required by Photologue.

Add the urls

Add photologue to your projects urls.py file:

urlpatterns += [
    ...
    url(r'^photologue/', include('photologue.urls', namespace='photologue')),
]

Sync Your Database

You can now sync your database:

python manage.py migrate photologue

If you are installing Photologue for the first time, this will set up some default PhotoSizes to get you started - you are free to change them of course!

Instant templates

Photologue comes with basic templates for galleries and photos, which are designed to work well with Twitter-Bootstrap. You can of course override them, or completely replace them. Note that all Photologue templates inherit from photologue/root.html, which itself just inherits from a site-wide base.html - you can change this to use a different base template.

Sitemap

The Sitemaps protocol allows a webmaster to inform search engines about URLs on a website that are available for crawling. Django comes with a high-level framework that makes generating sitemap XML files easy.

Install the sitemap application as per the instructions in the django documentation, then edit your project’s urls.py and add a reference to Photologue’s Sitemap classes in order to included all the publicly-viewable Photologue pages:

...
from photologue.sitemaps import GallerySitemap, PhotoSitemap

sitemaps = {...
            'photologue_galleries': GallerySitemap,
            'photologue_photos': PhotoSitemap,
            ...
            }
etc...

There are 2 sitemap classes, as in some cases you may want to have gallery pages, but no photo detail page (e.g. if all photos are displayed via a javascript lightbox).

Sites

Photologue supports Django’s site framework since version 2.8. That means that each Gallery and each Photo can be displayed on one or more sites.

Please bear in mind that photos don’t necessarily have to be assigned to the same sites as the gallery they’re belonging to: each gallery will only display the photos that are on its site. When a gallery does not belong the current site but a single photo is, that photo is only accessible directly as the gallery won’t be shown in the index.

Note

If you’re upgrading from a version earlier than 2.8 you don’t need to worry about the assignment of already existing objects to a site because a datamigration will assign all your objects to the current site automatically.

Note

This feature is switched off by default. See here to enable it and for more information.

Amazon S3

Photologue can use a custom file storage system, for example Amazon’s S3.

You will need to configure your Django project to use Amazon S3 for storing files; a full discussion of how to do this is outside the scope of this page.

However, there is a quick demo of using Photologue with S3 in the example_project directory; if you look at these files:

  • example_project/example_project/settings.py
  • example_project/requirements.txt

At the end of each file you will commented-out lines for configuring S3 functionality. These point to extra files stored under example_project/example_storages/. Uncomment these lines, run the example project, then study these files for inspiration! After that, setting up S3 will consist of (at minimum) the following steps:

  1. Signup for Amazon AWS S3 at http://aws.amazon.com/s3/.
  2. Create a Bucket on S3 to store your media and static files.
  3. Set the environment variables:
    • AWS_ACCESS_KEY_ID - issued to your account by S3.
    • AWS_SECRET_ACCESS_KEY - issued to your account by S3.
    • AWS_STORAGE_BUCKET_NAME - name of your bucket on S3.
  4. To copy your static files into your S3 Bucket, type python manage.py collectstatic in the example_project directory.

Note

This simple setup does not handle S3 regions.