snapserve

SnapServe 📸

A lightweight CLI photo server with admin authentication and React frontend. Start a photo server in seconds with drag-and-drop upload and responsive gallery.

Quick Start

# Run instantly with npx (no installation needed)
npx snapserve --admin mysecretpassword

# Server starts on http://localhost:3000
# Open in browser, enter your admin secret, and start uploading photos!

Features

• 🔐 Admin Authentication: Secure access with custom admin secret
• 📤 Drag & Drop Upload: Upload multiple photos with progress indication
• 🖼️ Responsive Gallery: Beautiful photo grid with metadata on hover
• 🚀 Zero Config: Works out of the box with sensible defaults
• 📱 Mobile Friendly: Responsive design works on all devices
• ⚡ Fast: Built with Vite + React + TypeScript + Tailwind CSS
• 🛡️ Secure: Session-based authentication with file validation

Installation & Usage

Option 1: NPX (Recommended)

# Run instantly without installation
npx snapserve --admin mysecretpassword

# Custom port and upload directory
npx snapserve --admin mysecret --port 8080 --dir ./my-photos

Option 2: Global Installation

# Install globally
npm install -g snapserve

# Run from anywhere
snapserve --admin mysecretpassword

Option 3: Local Development

# Clone and install
git clone <repository>
cd snapserve
npm install

# Run locally
npm start -- --admin mysecretpassword

API Endpoints

Authentication

• POST /api/auth - Login with admin secret
• GET /api/auth/status - Check authentication status
• POST /api/auth/logout - Logout

Photos (requires authentication)

• GET /api/photos - List all uploaded photos
• POST /api/photos/upload - Upload photos (multipart/form-data)

Static Files

• /uploads/* - Serve uploaded photos
• /* - Serve React app

CLI Options

snapserve [options]

Options:
  --admin <secret>     Admin secret password (required, min 3 chars)
  -p, --port <port>    Port to run server on (default: 3000)
  -d, --dir <dir>      Directory for uploads (default: ./uploads)
  -h, --help           Display help
  -V, --version        Display version

Examples:
  snapserve --admin mypassword123
  snapserve --admin secret --port 8080 --dir ~/Pictures

Testing

Comprehensive Test Results ✅

Authentication & Security

• ✅ Admin secret validation (correct/incorrect passwords)
• ✅ Session management and persistence
• ✅ Unauthorized access protection
• ✅ Secure logout functionality
• ✅ CLI parameter validation

Photo Management

• ✅ Photo upload with file validation
• ✅ Multiple file upload support
• ✅ Photo listing with metadata
• ✅ Static file serving
• ✅ Unique filename generation

Frontend Integration

• ✅ React app serving
• ✅ API integration
• ✅ Responsive design
• ✅ Error handling and user feedback
• ✅ Build process integration

CLI & Server

• ✅ Command-line argument parsing
• ✅ Server startup and shutdown
• ✅ Port configuration
• ✅ Directory creation
• ✅ Error messages and validation

Screenshots

Login Screen

Beautiful gradient login interface with admin secret authentication.

Photo Gallery

Responsive grid layout with hover effects showing photo metadata.

Upload Interface

Drag-and-drop upload with progress indication and file validation.

Supported File Types

• Images: JPG, JPEG, PNG, GIF, WebP
• Size Limit: 10MB per file
• Batch Upload: Up to 10 files at once

Security Features

• Admin secret-based authentication
• Session management with secure cookies
• File type validation
• Size limit enforcement
• Unauthorized access protection

Features Implemented

• Admin Secret Based Auth ✅

  • CLI accepts --admin <secret> parameter
  • Session-based authentication
  • Unauthorized requests return 401

• List All Photos ✅

  • Responsive photo gallery with hover effects
  • GET /api/photos returns JSON array
  • Supports common image formats
  • Shows metadata (filename, size, dates)

• Photo Upload ✅

  • Drag-and-drop interface with progress indication
  • POST /api/photos/upload accepts multipart data
  • File validation and size limits
  • Automatic unique filename generation

Technical Stack

• Backend: Node.js, Express.js, Multer v2
• Frontend: React 18, TypeScript, Vite 7
• Styling: Tailwind CSS
• Authentication: Express-session
• CLI: Commander.js
• File Upload: Multer with validation
• Build: Vite with PostCSS

File Structure

snapserve/
├── package.json
├── bin/snapserve.js          # CLI entry point
├── src/
│   ├── server.js             # Main server
│   └── routes/
│       ├── auth.js           # Authentication
│       ├── photos.js         # Photo management
│       └── static.js         # Static file serving
├── frontend/                 # React TypeScript app
│   ├── package.json
│   ├── vite.config.ts
│   ├── src/
│   │   ├── App.tsx           # Main app component
│   │   ├── api.ts            # API client
│   │   └── components/
│   │       ├── Login.tsx     # Admin login
│   │       ├── PhotoGallery.tsx  # Photo gallery
│   │       └── PhotoUpload.tsx   # Upload interface
│   └── dist/                 # Built React app
├── uploads/                  # Photo storage
└── README.md

Troubleshooting

Common Issues

Port already in use

# Use a different port
snapserve --admin mypassword --port 8080

Permission denied for uploads directory

# Specify a different directory
snapserve --admin mypassword --dir ~/my-photos

Admin secret too short

# Use at least 3 characters
snapserve --admin abc123

FAQ

Q: Can I change the admin secret while the server is running? A: No, you need to restart the server with a new --admin parameter.

Q: Where are photos stored? A: By default in ./uploads/ directory, or specify with --dir option.

Q: Can multiple users upload photos? A: Currently, it's single-admin only. Anyone with the admin secret can upload.

Q: Is this suitable for production? A: This is designed for personal/development use. For production, consider additional security measures.

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Test thoroughly
• Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 🐛 Issues: Report bugs on GitHub
• 💡 Feature Requests: Open an issue with your idea
• 📖 Documentation: Check the README and code comments