ChronoFrame

Languages: English | 中文

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

Live Demo: TimoYin's Mems

✨ 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, local filesystem
CDN acceleration - Configurable CDN URL for faster photo delivery

🐳 Deployment

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

Create a .env file and configure environment variables.

Below is a minimal configuration example. For complete configuration options, see Configuration Guide:

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

# Site metadata (all optional)
NUXT_PUBLIC_APP_TITLE=
NUXT_PUBLIC_APP_SLOGAN=
NUXT_PUBLIC_APP_AUTHOR=
NUXT_PUBLIC_APP_AVATAR_URL=

# Map provider (maplibre/mapbox)
NUXT_PUBLIC_MAP_PROVIDER=maplibre
# MapTiler access token for MapLibre
NUXT_PUBLIC_MAP_MAPLIBRE_TOKEN=
# Mapbox access token for Mapbox
NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=

# Mapbox unrestricted token (optional, reverse geocoding)
NUXT_MAPBOX_ACCESS_TOKEN=

# Storage provider (local, s3 or openlist)
NUXT_STORAGE_PROVIDER=local
NUXT_PROVIDER_LOCAL_PATH=/app/data/storage

# Session password (32‑char random string, required)
NUXT_SESSION_PASSWORD=

Pull Image

Use the published image on GitHub Container Registry and Docker Hub. Choose the source that works best for your network:

GitHub Container Registry (GHCR)

docker pull ghcr.io/hoshinosuzumi/chronoframe:latest

Docker Hub

docker pull hoshinosuzumi/chronoframe:latest

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

📖 User Guide

If CFRAME_ADMIN_EMAIL and CFRAME_ADMIN_PASSWORD are not set, the default admin account is:

Email: admin@chronoframe.com

Password: CF1234@!

Logging into the Dashboard

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

Uploading Photos

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

📸 Screenshots

Gallery Photo Detail Map Explore Dashboard

🛠️ Development

Requirements

Node.js 18+
pnpm 9.0+

Install dependencies

# With pnpm (recommended)
pnpm install

# Or with other package managers
npm install
yarn install

Configure environment variables

cp .env.example .env

Initialize database

# 2. Generate migration files (optional)
pnpm db:generate

# 3. Run database migrations
pnpm db:migrate

Start development server

pnpm dev

App will start at http://localhost:3000.

Project Structure

chronoframe/
├── app/                    # Nuxt app
│   ├── components/         # Components
│   ├── pages/              # Page routes
│   ├── composables/        # Composables
│   └── stores/             # Pinia stores
├── packages/
│   └── webgl-image/        # WebGL image viewer
├── server/
│   ├── api/                # API routes
│   ├── database/           # DB schema & migrations
│   └── services/           # Business logic services
└── shared/                 # Shared types & utils

Build commands

# Development (with dependencies build)
pnpm dev

# Build only dependencies
pnpm build:deps

# Production build
pnpm build

# Database operations
pnpm db:generate    # Generate migration files
pnpm db:migrate     # Run migrations

# Preview production build
pnpm preview

🤝 Contributing

Contributions are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add some amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Coding Guidelines

Use TypeScript for type safety
Follow ESLint and Prettier conventions
Update documentation accordingly

📄 License

This project is licensed under the MIT License.

👤 Author

Timothy Yin

Email: master@uniiem.com
GitHub: @HoshinoSuzumi
Website: bh8.ga
Gallery: lens.bh8.ga

❓ FAQ

<details> <summary>How is the admin user created?</summary> On first startup, an admin user is created based on <code>CFRAME_ADMIN_EMAIL</code>, <code>CFRAME_ADMIN_NAME</code>, and <code>CFRAME_ADMIN_PASSWORD</code>. The email must match your GitHub account email used for login. </details> <details> <summary>Which image formats are supported?</summary> Supported formats: JPEG, PNG, HEIC/HEIF, MOV (for Live Photos). </details> <details> <summary>Why can’t I use GitHub/Local storage?</summary> Currently only S3-compatible storage is supported. GitHub and local storage support is planned. </details> <details> <summary>Why is a map service required and how to configure it?</summary> The map is used to browse photo locations and render mini-maps in photo details. Currently Mapbox is used. After registering, <a href="https://console.mapbox.com/account/access-tokens/">get an access token</a> and set it to the <code>MAPBOX_TOKEN</code> variable. </details> <details> <summary>Why wasn’t my MOV file recognized as a Live Photo?</summary> Ensure the image (.heic) and video (.mov) share the same filename (e.g., <code>IMG_1234.heic</code> and <code>IMG_1234.mov</code>). Upload order does not matter. If not recognized, you can trigger pairing manually from the dashboard. </details> <details> <summary>How do I import existing photos from storage?</summary> Direct import of existing photos is not yet supported. A directory scanning import feature is planned. </details> <details> <summary>How is this different from Afilmory?</summary> Afilmory generates a manifest from photos during local/CI processing and serves them statically. ChronoFrame is a dynamic photo management app, offering online upload, management, and browsing—better for frequently updated galleries. In other words, Afilmory = static; ChronoFrame = dynamic, online upload/manage. </details>

Chronoframe

Install / Use

README