Lychee

Lychee is a self‑hosted photo management system built to run on any web server that supports PHP 8.3+. At its core, it is a web application that exposes a REST‑style API for CRUD operations on images, albums, and tags while also delivering a rich JavaScript front‑end that mimics the experience of a native photo gallery. The application is designed to be lightweight, secure, and highly extensible, making it a popular choice for developers who need a turnkey solution that can be customized or integrated into larger ecosystems.

Architecture

Lychee follows a classic MVC pattern using the Symfony framework as its backbone. The backend is written in PHP, leveraging Symfony components for routing, security, and form handling. Data persistence is handled by Doctrine ORM, which abstracts the underlying database layer; Lychee supports MySQL/MariaDB, PostgreSQL, and SQLite out of the box. Media files themselves are stored on the filesystem (or any storage provider that implements Symfony’s FilesystemInterface), while metadata is kept in the relational database. The front‑end is a single‑page application built with Vue.js, communicating with the PHP API via JSON over HTTPS. This separation allows developers to swap out either layer independently—for example, by replacing the Vue client with a React or Angular implementation—without touching core logic.

Core Capabilities

From a developer standpoint, Lychee offers:

• RESTful API: Endpoints for uploading images, creating albums, tagging, and sharing links. The API is fully documented in OpenAPI format, enabling automated client generation.
• Webhooks: Configurable webhook hooks that fire on events such as image upload or album deletion, allowing integration with CI/CD pipelines or external notification services.
• Plugin System: A lightweight plugin architecture based on Symfony bundles. Developers can extend Lychee by adding new services, routes, or UI components without modifying the core codebase.
• Authentication & Authorization: Supports Symfony Security, including LDAP and OAuth2 providers. Fine‑grained ACLs let you expose only specific albums or images to external users.
• Batch Operations: Bulk upload, deletion, and tagging via the API or CLI commands, useful for automated migrations.

Deployment & Infrastructure

Lychee is intentionally minimalistic: a web server (Apache/Nginx), PHP, and a supported database. For rapid onboarding, the project ships with an official Docker image (lycheeorg/lychee) that bundles PHP 8.3, the required extensions, and a pre‑configured Nginx server. The Docker image is built on Alpine Linux for reduced attack surface and smaller footprint. For production, the recommended deployment pattern is a stateless API container behind a load balancer, with shared storage (e.g., NFS or an object store) for media files. This architecture scales horizontally by simply adding more API replicas; the database remains a single source of truth, while media storage can be replicated or mirrored as needed.

Integration & Extensibility

Because Lychee exposes a clean API and follows Symfony conventions, it integrates smoothly with existing PHP ecosystems. Developers can embed Lychee as a sub‑application in larger monoliths or expose its endpoints to mobile apps. The plugin system lets you hook into the request lifecycle, add custom validation rules, or replace the default image processing pipeline (e.g., integrate with ImageMagick or a cloud‑based transcoder). Webhooks and event listeners make it trivial to trigger side effects—such as updating a search index or notifying a Slack channel—whenever media changes occur.

Developer Experience

The project maintains comprehensive, up‑to‑date documentation that covers everything from API usage to plugin development. Code quality is monitored through CI pipelines, automated tests (over 80% coverage), and adherence to CII Best Practices. The community is active on Gitter, Discord, and GitHub Discussions, providing rapid support for integration questions. Licensing is MIT, giving developers freedom to modify or redistribute the code without copyleft constraints.

Use Cases

• Personal Cloud Photo Server: A developer can deploy Lychee on a home NAS or VPS, granting themselves and trusted friends secure access to shared albums.
• Enterprise Asset Management: Companies can use Lychee as a lightweight CMS for marketing images, integrating it with LDAP for user management and an internal CDN for fast delivery.
• Event Photography Platform: Photographers can host Lychee on a Docker Swarm, automatically creating temporary albums for each event and sharing download links with clients.
• Open‑Source Photo Repository: Nonprofits or community projects can expose Lychee as a public gallery, leveraging its API to sync with other services (e.g., WordPress galleries or static site generators).

Advantages

Lychee’s combination of a modern PHP stack, Vue.js front‑end, and Docker support makes it easier to maintain than legacy photo managers. Its lightweight footprint (under 200 MB for the Docker image) and lack of heavy dependencies enable quick scaling. The MIT license removes legal friction, while the plugin architecture ensures that future features can be added without forking. Finally, the active community and thorough testing pipeline reduce technical debt, allowing developers to focus on building unique integrations rather than patching bugs.