picjava

A self-hosted image hosting web app — a Java 21 / Spring Boot. Upload, browse, and delete pictures from a private dashboard with automatic thumbnail generation.

• Single-admin login with rate-limited brute-force protection (5 attempts, 15-minute lockout)
• Upload JPEG, PNG, GIF, and WebP images up to 32 MB
• Automatic thumbnail generation with EXIF orientation correction
• Paginated dashboard (20 images per page)
• SQLite-backed metadata store (WAL mode)
• CSRF protection on all mutating actions
• 1-year cache headers on served images
• Structured request logging
• Virtual threads (Project Loom) for request handling and thumbnail generation

./mvnw spring-boot:run

The server starts on port 8080. Visit http://localhost:8080 and log in with the default credentials (admin / password123).

Data is stored under ./data/ — uploaded files in data/uploads/, thumbnails in data/uploads/thumbs/, and the SQLite database at data/picgo.db. The database schema and file layout are identical to picgo, so pointing DATA_DIR at an existing picgo data directory works as a drop-in migration.

To run the tests:

./mvnw test

All configuration is via environment variables:

Build and run with Docker:

docker build -t picjava .
docker run -p 8080:8080 -v $(pwd)/data:/app/data \
  -e ADMIN_PASSWORD=yourpassword \
  picjava

Or with Docker Compose:

services:
  picjava:
    image: ghcr.io/your-org/picjava:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      ADMIN_PASSWORD: yourpassword
      SECURE_COOKIES: "true"
    restart: unless-stopped

GitHub Actions runs on every push and pull request to main:

1. Build — ./mvnw -B verify (compiles and runs the test suite)
2. Docker — builds and pushes the image to GHCR (ghcr.io/<owner>/<repo>:latest and :<sha>) on pushes to main
3. Deploy — SSHes into a VPS, pulls the new image, and restarts via docker compose

Required repository secrets for deployment: VPS_HOST, VPS_USER, VPS_SSH_KEY, VPS_PORT, VPS_COMPOSE_DIR, GHCR_TOKEN, GHCR_USER.

• Java 21 with Spring Boot 4.1 (Web MVC, Thymeleaf, JDBC)
• SQLite via sqlite-jdbc
• Thumbnailator for thumbnail generation and EXIF orientation correction
• TwelveMonkeys ImageIO for WebP decoding

Authentication is deliberately hand-rolled (DB-backed session tokens, per-session CSRF tokens, per-IP login rate limiting) to mirror picgo's behavior exactly, rather than pulling in Spring Security.