Welcome to Goldplated Photos¶

A beautiful, secure, self-hosted photo gallery for photographers and enthusiasts.

Built with Astro + PhotoSwipe by Kristijan Lukacin and Claude AI

Live Demo GitHub

Why Goldplated Photos?¶

True Privacy

Self-hosted on your own server. No cloud services, no third-party tracking. Your photos stay yours.
No Database

File-based architecture using folders and markdown. Easy to backup, version control, and migrate.
Modern Stack

Built with Astro 5, PhotoSwipe 5, and Sharp. Fast, modern, and actively maintained.
Human + AI Built

Crafted by Kristijan Lukacin with Claude AI assistance. Includes CLAUDE.md for AI-assisted development.

Features¶

Gallery Experience¶

Multiple View Modes - Grid, Masonry, Single-column, and Slideshow layouts
PhotoSwipe Lightbox - Touch gestures, pinch-to-zoom, swipe navigation
EXIF Display - Camera settings, lens info, and shooting parameters
Video Support - Inline playback with metadata extraction (ffprobe)
Keyboard Navigation - Full accessibility with arrow keys and shortcuts

Organization¶

Hierarchical Albums - Nested folder structure for organization
Collections - Group related albums together
Custom Ordering - Control album display order via frontmatter
Cover Photos - Auto-detected or manually selected

Security¶

Password Protection - Server-side access control (SSR)
Rate Limiting - 10 failed attempts per 15 minutes per IP
Secure Cookies - HttpOnly, Secure, SameSite strict flags
Path Traversal Protection - All API endpoints secured

Performance¶

Smart Thumbnails - Three sizes (400px, 1200px, 1920px)
On-demand Generation - Thumbnails created on first request
Persistent Caching - Thumbnails cached for instant loading
EXIF Auto-rotation - Correct orientation guaranteed

Quick Start¶

# Clone the repository
git clone https://github.com/klukacin/goldplated-photos
cd goldplated-photos

# Install dependencies
npm install

# Start development server
npm run dev

Visit http://localhost:4321 to see your gallery.

For detailed setup instructions, see the Installation Guide.

Site Structure¶

Route	Description
`/`	Landing page with animated shutter button
`/home`	Digital home with hero slider and content cards
`/photos`	Photo gallery root with album browser
`/photos/*`	Individual albums and collections

Adding Photos¶

Create an album folder in src/content/albums/
Add an index.md file with metadata
Copy your photos to the folder
Photos are auto-discovered and thumbnails generated on first view

# src/content/albums/2025/vacation/index.md
---
title: "Summer Vacation"
thumbnail: "beach-sunset.jpg"
password: "secret"  # Optional
---

For more details, see Adding Albums.

Admin Panel¶

A local web-based CMS for content management (never deployed to production).

npm run admin     # Start on port 4444

Features:

Album creation and editing
Photo/video upload via drag-and-drop
Hero slider image management
Content card editor
Thumbnail cache management

See Admin Panel Guide for full documentation.

Documentation¶

Getting Started¶

Installation - Full setup guide with prerequisites
Quick Start - Get running in 5 minutes
Configuration - Environment variables and options

Guides¶

Adding Albums - Album structure and frontmatter
Admin Panel - Using the local CMS
Deployment - Production server setup
Customization - Theming and styling
Using Claude AI - AI-assisted development

Reference¶

Architecture - Technical deep-dive
API Endpoints - All API routes
Keyboard Shortcuts - Navigation keys
UI Components - Component documentation

Contributing¶

We welcome contributions! See the Contributing Guide for guidelines.

This project includes CLAUDE.md for AI-assisted development with Claude Code.

License¶

MIT License - See LICENSE

Created by Kristijan Lukacin with Claude AI assistance