hoshinosuzumi/chronoframe repository overview

A smooth photo display and management application, supporting multiple image formats and large-size image rendering.

Useful links: Live Demo⁠ | Documention⁠ | GitHub Repository⁠

⁠✨ Features

⁠🖼️ Powerful Photo Management

• Manage photos online - Easily manage and browse photos via the web interface
• Explore map - Browse photo locations on a map
• Smart EXIF parsing - Automatically extracts metadata such as capture time, geolocation, and camera parameters
• Reverse geocoding - Automatically identifies photo shooting locations
• Multi-format support - Supports mainstream formats including JPEG, PNG, HEIC/HEIF
• Smart thumbnails - Efficient thumbnail generation using ThumbHash

⁠🔧 Modern Tech Stack

• Nuxt 4 - Built on the latest Nuxt framework with SSR/SSG support
• TypeScript - Full type safety
• TailwindCSS - Modern CSS framework
• Drizzle ORM - Type-safe database ORM

⁠☁️ Flexible Storage Solutions

• Multiple storage backends - Supports S3-compatible storage, GitHub (WIP), and local filesystem (WIP)
• CDN acceleration - Configurable CDN URL for faster photo delivery

⁠🐳 Deployment

We recommend deploying with the prebuilt Docker image. View the image on ghcr⁠

Before deployment, create a .env file and configure environment variables. Refer to .env.example⁠.

# Admin user email (required)
CFRAME_ADMIN_EMAIL=
# Admin user name (default to Chronoframe, optional)
CFRAME_ADMIN_NAME=
# Admin user password (default to CF1234@!, optional)
CFRAME_ADMIN_PASSWORD=

# App info
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
NUXT_PUBLIC_APP_AVATAR_URL=

# Mapbox access token for map features, Mapbox GL JS (Client-side, public)
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=
# Mapbox secret access token for server-side, Mapbox Search API (Reverse Geocoding)
NUXT_MAPBOX_ACCESS_TOKEN=

# Storage provider (s3/github/local)
NUXT_STORAGE_PROVIDER=s3
# S3 storage config
NUXT_PROVIDER_S3_ENDPOINT=
NUXT_PROVIDER_S3_BUCKET=chronoframe
NUXT_PROVIDER_S3_REGION=auto
NUXT_PROVIDER_S3_ACCESS_KEY_ID=
NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=
NUXT_PROVIDER_S3_PREFIX=photos/
NUXT_PROVIDER_S3_CDN_URL=

# Session password (32 chars, required)
NUXT_SESSION_PASSWORD=

# GitHub OAuth
NUXT_OAUTH_GITHUB_CLIENT_ID=
NUXT_OAUTH_GITHUB_CLIENT_SECRET=

⁠Docker

Run with customized environment variables:

docker run -d --name chronoframe -p 3000:3000 -v $(pwd)/data:/app/data --env-file .env ghcr.io/hoshinosuzumi/chronoframe:latest

⁠Docker Compose

Create docker-compose.yml:

services:
  chronoframe:
    image: ghcr.io/hoshinosuzumi/chronoframe:latest
    container_name: chronoframe
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - ./data:/app/data
    env_file:
      - .env

Start:

docker-compose up -d

⁠Environment Variables

⁠📖 User Guide

⁠Logging into the Dashboard

1. Click avatar to sign in with GitHub OAuth or use email/password login

⁠Uploading Photos

1. Go to the dashboard at /dashboard
2. On the Photos page, select and upload images (supports batch & drag-and-drop)
3. System will automatically parse EXIF data, generate thumbnails, and perform reverse geocoding