riadvice/placepix repository overview

⁠PlacePix

Self-hosted placeholder image server. Drop in your own images and serve them with on-the-fly resizing, filters, and format conversion — like picsum.photos, but entirely under your control.

⁠Supported tags

• latest — stable release

⁠Quick Start

docker run -d \
  -p 3000:3000 \
  -v $(pwd)/images:/app/images \
  --name placepix \
  riadvice/placepix:latest

Or with Docker Compose:

services:
  placepix:
    image: riadvice/placepix:latest
    ports:
      - "3000:3000"
    volumes:
      - ./images:/app/images
      - ./.cache:/app/.cache
    restart: unless-stopped

1. Put images in ./images/ (subfolders become categories)
2. Open http://localhost:3000 for the interactive URL builder
3. Use it in HTML: <img src="http://localhost:3000/300/200" />

⁠Features

• On-the-fly processing — resize, crop, cover, scale, contain, or smart crop (OpenCV face detection)
• Filters & effects — grayscale, blur, sepia, noise, pixelate, tint, brightness, contrast, saturation, and more
• Multiple formats — JPEG, PNG, WebP, AVIF
• Solid color placeholders — /solid/500/300/ff0000 with optional text overlay
• Aspect ratio sizing — /ratio/16:9/1080
• Preset dimensions — Instagram, YouTube, Facebook, LinkedIn, and more
• Orientation filtering — filter by landscape, portrait, or squarish
• Watermark overlay — image or text with positioning and opacity
• Srcset generation — responsive image sets via /api/srcset
• Upload API — add images via POST /api/upload
• Admin dashboard — password-protected usage metrics
• Browser caching — ETag, Last-Modified, 304 responses
• S3 storage — optional S3-compatible backend (OVHcloud, AWS, MinIO, etc.)
• AI generation (experimental) — OVHcloud AI Endpoints integration

⁠Environment Variables

See .env.example⁠ for the full list.

⁠URL Examples

GET /300/200                    # Random image, 300x200
GET /300/200.webp               # WebP format
GET /300/200/nature             # From "nature" category
GET /300/200?grayscale=true     # With filter
GET /300/200?text=Hello         # With text overlay
GET /ratio/16:9/1080            # Aspect ratio sizing
GET /preset/instagram-square    # Preset dimensions
GET /solid/500/300/ff0000       # Solid color placeholder

Full API reference: placepix.net/guide⁠

⁠Links

• Source: github.com/riadvice/placepix⁠
• Live demo: placepix.net⁠
• Documentation: placepix.net/guide⁠

⁠Quick Reference

• Where to get help: GitHub Discussions⁠
• Where to file issues: GitHub Issues⁠
• Source repository: github.com/riadvice/placepix⁠
• Full documentation: placepix.net/guide⁠
• Live demo: placepix.net⁠

⁠License

MIT — see LICENSE⁠.