ggallery 1.1.2

Add your description here

ggallery

ggallery is a Python tool that generates a static HTML photo gallery website from a YAML specification and from given renderer plugin. It allows you to create beautiful and customizable photo galleries with ease, using various data sources and storage providers.

Features

• Static HTML Generation using plugins: Create a static HTML photo gallery that can be hosted on any web server, using a custom renderer plugin.
• Multiple Data Sources: Supports local file system and Azure Blob Storage as data sources.
• Thumbnail Generation: Automatically generate thumbnails for your images.
• Docker image creation: Create a Docker image (using nginx) with the generated gallery.

Available Renderer Plugins

• https://github.com/creeston/ggallery-nanogallery2 - template built on top of nanogallery2 and bulma css framework. Live Demo

Usage

To install ggallery, you need to have Python with pip package manager in your system. Then you can install the tool using the following command:

pip install ggallery

You can run the ggallery using the following commands:

python -m ggallery -f /path/to/your/gallery.yaml

or

ggallery -f /path/to/your/gallery.yaml

If you have the gallery.yaml file in the current directory, you can run the tool without specifying the file path:

ggallery

Gallery Specification Examples

Local Gallery with Docker Image

Photos and HTML files are stored in the same directory as the static website. It will procude a directory ready to be served by a web server.

1. Set environment variables (or create .env file)

• LOCAL_PHOTOS_PATH: Path to the directory containing photos.
• DOCKER_HOST Hostname of the Docker host. (e.g tcp://localhost:2375)

2. Create a gallery.yaml file with the following content:

title: Local Gallery
subtitle: Gallery with photos stored in the same directory as static website.

thumbnail:
    height: 400

template:
    url: https://github.com/creeston/ggallery-nanogallery2

data_source:
    type: local
    path: "${LOCAL_PHOTOS_PATH}" # Path to the directory containing photos.

data_storage:
    type: local # Store photos in the same directory as the static website.

albums:
    - title: "Japan"
      subtitle: "Photos from my trip to Japan"
      source: "japan"
      cover: "view on the Fuji.jpg"

    - title: "Italy"
      source: "italy"
      cover: "colliseum.jpg"
      photos:
          - title: "View at the Colosseum at night"
            source: "colliseum.jpg"

# Output directory for the generated gallery website.
output:
    path: docs
    index: index.html

# Docker image configuration
docker:
    image_name: "username/my-photo-gallery"
    image_version: "latest"
    host: "${DOCKER_HOST}"

Azure Blob Storage Example

Photos are stored in Azure Blob Storage. The generated gallery will contain links to the photos stored in Azure Blob Storage.

1. Set environment variables (or create .env file)

• LOCAL_PHOTOS_PATH: Path to the directory containing photos.
• AZURE_CONTAINER: Azure Blob Storage container name.
• AZURE_CONNECTION_STRING: Azure Blob Storage connection string.

2. Create a gallery.yaml file with the following content:

title: Azure Gallery
subtitle: Gallery of photos stored in Azure Blob Storage

favicon:
    type: fontawesome
    name: camera-retro

thumbnail:
    height: 400

template:
    url: https://github.com/creeston/ggallery-nanogallery2

data_source:
    type: local
    path: "${LOCAL_PHOTOS_PATH}"

# Azure Blob Storage configuration, used to store photos and thumbnails.
data_storage:
    type: azure-blob
    container: "${AZURE_CONTAINER}"
    connection_string: "${AZURE_CONNECTION_STRING}"

albums:
    - title: "Japan"
      subtitle: "Photos from my trip to Japan"
      source: "japan"
      cover: "view on the Fuji.jpg"

    - title: "Italy"
      source: "italy"
      cover: "colliseum.jpg"
      photos:
          - title: "View at the Colosseum at night"
            source: "colliseum.jpg"

output:
    path: docs
    index: index.html

Implementing a Custom Template

ggallery doesn't contain any templates by default. You can create your own plugin by implementing ggalllery.renderers.BaseRenderer class. The plugin can be stored either locally or in a public github repository. URL to the repository should be provided in the gallery.yaml file in the template.url field.

Examples:

• https://github.com/creeston/ggallery-nanogallery2

Live Gallery Examples

• https://creeston.github.io/photos/ (Photos hosted on Azure Blob Storage, website is on GitHub Pages)
• https://radzivon-gallery-hsgrctdhdwe7bgf0.polandcentral-01.azurewebsites.net/ (Docker image hosted on Azure App Service)

References

ggallery uses the following technologies:

• Pillow: A Python Imaging Library.
• Azure Storage Blob: Azure Blob Storage client library for Python.
• PyYAML: YAML parser and emitter for Python.

Contribution

Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Development

To set up a development environment, create a virtual environment and install the required packages:

1. Install uv and pip if you haven't already. (https://github.com/astral-sh/uv)

2. Install dependencies using uv:

uv sync

Build

python -m build

Update PyPI

python -m twine upload dist/*