Photon

A self-hosted photo and video management application.

Features

• Photo and video upload with automatic thumbnail generation
• EXIF data extraction and display
• GPS location support with map display
• Albums for organizing media
• Share links with optional password protection
• Multi-user support with admin panel
• Dark/light theme
• Responsive design

Tech Stack

• Backend: Node.js, Fastify, Drizzle ORM, PostgreSQL
• Frontend: React, Vite, TailwindCSS, TanStack Query, Zustand
• Media Processing: Sharp, FFmpeg, exifr
• Infrastructure: Docker, GitHub Actions

Quick Start

Development

1. Clone the repository:

   git clone https://github.com/clucraft/Photon.git
   cd Photon

2. Install dependencies:

   pnpm install

3. Start the development environment:

   docker-compose up

4. Access the application:

   • Frontend: http://localhost:5173
   • API: http://localhost:3000

5. Register the first user (will become admin automatically)

Production

1. Copy the environment example:

   cp .env.example .env

2. Edit .env with your production values (especially JWT_SECRET and POSTGRES_PASSWORD)

3. Start the production environment:

   docker-compose -f docker-compose.prod.yml up -d

Project Structure

Photon/
├── .github/workflows/     # CI/CD pipelines
├── apps/
│   ├── api/              # Fastify backend
│   │   ├── src/
│   │   │   ├── db/       # Drizzle schema
│   │   │   ├── modules/  # Route modules
│   │   │   ├── services/ # Business logic
│   │   │   └── middleware/
│   │   └── Dockerfile
│   └── web/              # React frontend
│       ├── src/
│       │   ├── components/
│       │   ├── pages/
│       │   ├── stores/
│       │   └── api/
│       └── Dockerfile
├── docker-compose.yml     # Development
├── docker-compose.prod.yml # Production
└── storage/              # Media files

API Endpoints

Auth

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login
• POST /api/v1/auth/refresh - Refresh access token
• POST /api/v1/auth/logout - Logout
• GET /api/v1/auth/me - Get current user

Media

• GET /api/v1/media - List media (paginated)
• GET /api/v1/media/:id - Get single media
• GET /api/v1/media/timeline - Get media timeline
• POST /api/v1/media/upload - Upload media
• PUT /api/v1/media/:id/favorite - Toggle favorite
• DELETE /api/v1/media/:id - Move to trash
• POST /api/v1/media/:id/restore - Restore from trash
• DELETE /api/v1/media/:id/permanent - Permanently delete

Albums

• GET /api/v1/albums - List albums
• POST /api/v1/albums - Create album
• GET /api/v1/albums/:id - Get album
• PUT /api/v1/albums/:id - Update album
• DELETE /api/v1/albums/:id - Delete album
• GET /api/v1/albums/:id/media - Get album media
• POST /api/v1/albums/:id/media - Add media to album

Shares

• GET /api/v1/shares - List user's shares
• POST /api/v1/shares - Create share
• DELETE /api/v1/shares/:id - Delete share
• GET /api/v1/shares/s/:token - Access shared content

Admin

• GET /api/v1/admin/stats - Get system stats
• GET /api/v1/admin/users - List users
• POST /api/v1/admin/users - Create user
• PUT /api/v1/admin/users/:id - Update user
• DELETE /api/v1/admin/users/:id - Delete user

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	-
JWT_SECRET	Secret for JWT signing	-
STORAGE_PATH	Path to media storage	./storage
MAX_FILE_SIZE	Max upload size in bytes	104857600
CORS_ORIGIN	Allowed CORS origin	http://localhost:5173

License

MIT