spectra/README.md

Spectra

A variation on the masonry grid image gallery with the row alighment constraint removed. Oh, it also has an admin interface so you can set it up and forget it.

Features

• Color Analysis: Automatically extracts color palettes from images to create cohesive galleries
• Smart Thumbnails: Generates and caches responsive thumbnails in multiple sizes
• EXIF Preservation: Maintains all photo metadata through processing
• Ownership Verification: Embeds steganographic proofs in images
• Live Configuration: Hot-reload config changes without restarts
• Production Ready: Fully Dockerized with Traefik integration

Quick Start

Local Development

Clone the repository

git clone https://git.dws.rip/your-username/spectra
cd spectra

Set up Python virtual environment

python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows

Install dependencies

pip install -r requirements.txt

Create config from template

cp config.example.toml config.toml

Run development server

python app.py

Production Deployment

Create required network

docker network create traefik-public

Configure your domain

sed -i 's/photos.dws.rip/your.domain.here/g' docker-compose.yml

Launch

docker-compose up -d

Configuration

Essential Settings

[server]
host = "0.0.0.0"
port = 5000
[security]
max_upload_size_mb = 80
rate_limit = 100 # requests per minute
[admin]
password = "change-this-password" # Required

See config.example.toml for all available options.

Directory Structure

spectra/
├── app.py # Application entry point
├── config.py # Configuration management
├── models.py # Database models
├── steganography.py # Image verification
├── templates/ # Jinja2 templates
├── uploads/ # Original images
└── thumbnails/ # Generated thumbnails

API Reference

Endpoints

Public Endpoints

• GET / - Main gallery view
• GET /api/images - Get paginated image list
• GET /verify/<filename> - Verify image authenticity

Admin Endpoints

• POST /admin/login - Admin authentication
• POST /admin/upload - Upload new images
• POST /admin/update_photo/<id> - Update image metadata
• POST /admin/delete_photo/<id> - Delete image

Environment Variables

• FLASK_ENV: Set to 'production' in production
• WORKERS: Number of Gunicorn workers (default: 4)
• PORT: Override default port (default: 5000)

Release Process

To create a release:

• Create and push a tag: git tag v1.0.0 && git push origin v1.0.0
• Create a release in Gitea UI using that tag
• The workflow will build and push the Docker image with appropriate version tags
• The Docker image will be available at: git.dws.rip/your-repo/image:v1.0.0