picpan（pic盘）

A self-hostable, S3-native photo album manager. Store your photos in your own S3-compatible bucket (Backblaze B2, Wasabi, Cloudflare R2, Hetzner, MinIO, …), keep them encrypted at rest, and share a private album server with family and friends — without handing your library to a third-party cloud.

See CLAUDE.md for the product rationale and TECHNICAL.md for architecture details.

Features

• Auth — username + password (NextAuth, bcrypt), with ADMIN and USER roles. Admins manage user accounts and can reset passwords or change roles.
• Upload + thumbnails — server-side upload generates two thumbnails (small ~300px, medium ~800px) plus a re-encoded original, all via Sharp.
• Encrypted at rest — every derivative is AES-256-GCM encrypted before it reaches the bucket; the private bucket only ever holds .enc blobs.
• Albums — private, public, and password-protected shared albums.
• Per-photo public CDN publishing — publish individual photos to a separate public bucket and get stable, immutable, cacheable CDN URLs to embed on external sites.
• Trash — soft delete with configurable retention.
• De-duplication — identical uploads are detected by content hash.
• Provider-agnostic keys — object keys encode no provider details, so you can switch S3 providers without re-architecting.
• Setup wizard — first-run wizard for storage/CDN configuration.

Stack

Next.js 16 (App Router) · Prisma 7 + Postgres · Sharp · AWS SDK v3 · NextAuth · Ant Design · Docker

Getting started (development)

Requires Bun and a Postgres database.

1. Install dependencies: bun install
2. Copy env and fill it in: cp .env.example .env
   • DATABASE_URL — your Postgres connection string
   • NEXTAUTH_SECRET — generate with openssl rand -base64 32
3. Create the schema: bun run db:push (or bun run db:migrate to use migration history)
4. Seed the admin user: bun run db:seed — creates admin / changeme (change the password after first login)
5. Start the dev server: bun run dev → http://localhost:3000
6. On first visit you'll be redirected to /setup to enter your S3 and CDN configuration. After that, log in as admin.

Scripts

• bun run dev — start the dev server
• bun run build / bun run start — production build / serve
• bun run lint — ESLint
• bun run db:generate — regenerate the Prisma client
• bun run db:push — push the schema to the database (no migration files)
• bun run db:migrate — create and apply a dev migration
• bun run db:seed — seed the admin user

Deployment (Docker)

The app ships as a container image. Postgres can be external or run alongside the app.

• External database — set DATABASE_URL (and IMAGE, PORT, NEXTAUTH_SECRET, NEXTAUTH_URL) in .env, then:

  docker compose up -d

• Bundled Postgres — leave DATABASE_URL blank, set POSTGRES_* in .env, then bring up both compose files:

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

Put a reverse proxy (Caddy for automatic HTTPS) or a Cloudflare Tunnel in front of the app — see the deployment targets in CLAUDE.md. Runtime configuration lives in a single Instance row created by the /setup wizard on first run; beyond secrets and the database URL there is nothing else to set in the environment.