简体中文
EnglishHow to Deploy Lychee with Docker
Updated
Lychee is a free, open-source, self-hosted photo management tool that runs on your own server or web space. According to the official site, it can be deployed with Docker in "a matter of seconds" using a provided docker-compose file, and there is a Docker Compose Wizard plus a "Deploy now" entry point to help you get started. This guide walks through the general Docker deployment flow, what to prepare, and how to verify it worked.
What Lychee Is and Why Self-Host It
Lychee is positioned as self-hosted photo management "made for photographers, by photographers." The site states:
- Your server, your data, your rules — it is a self-hosted solution, so you keep full control of your photos.
- No storage limit, no compression, no loss in data — it is designed as a place to store all your photos.
- EXIF and IPTC metadata support — photo metadata is displayed and always one click away.
- Open source — anyone can use and improve the work.
These points matter for the deployment decision: you are not signing up for a hosted service, you are running the application yourself.
Prerequisites
Before deploying, confirm you have:
- A server or web space where you can run Docker (the official site presents Docker as a first-class deployment path).
- Docker and Docker Compose installed on that machine.
- A place to store your photo library (a mounted volume or directory) so data survives container restarts.
- A domain or IP address if you want to reach the instance from outside your local network.
The site does not publish specific hardware requirements, minimum versions, or a fixed list of environment variables on the page evidence provided, so treat those as things to confirm against the project's own Docker documentation and compose file.
Deployment Steps
1. Get the docker-compose file
The official site points to a docker-compose file and a Docker Compose Wizard. Use the wizard to generate a compose configuration, or take the provided compose file as your starting point.
2. Review and adjust the compose file
Open the compose file and check the parts that are environment-specific:
- Volume mounts — point the photo storage path at a directory on your host so your library persists.
- Ports — decide which host port maps to the container's web port.
- Database — if the compose file includes a database service, keep its credentials and volume in the same file so the stack starts together.
3. Start the stack
From the directory containing your compose file, run the standard Compose up command. The expected result is that the Lychee container (and any database container) start and stay running.
4. Complete first-run setup
Open the instance in your browser at the address and port you configured. The expected result is the Lychee web interface, where you can create albums and upload photos.
Verifying the Deployment
After the stack is up, confirm:
- The web interface loads in your browser.
- You can upload a photo and see it appear in an album.
- The photo's EXIF/IPTC metadata is displayed, since the site states this is supported and shown next to other information.
- Restarting the containers does not lose your uploaded photos (this confirms your volume mount is correct).
Managing and Sharing After Deployment
Once running, the site describes the day-to-day features you will use:
| Area | What the site says you can do |
|---|---|
| Manage | Upload, move, rename, describe, delete, or search photos from your browser |
| Share | One click to make a photo or album public; albums can be password-protected |
| View | Full-screen viewing, keyboard navigation forward and backward |
| Import | Import from a local computer, server, via URL, or from Dropbox |
| Tag | Tag photos or mark them as important, individually or in batch |
| Batch | Desktop-like multi-select for acting on many photos at once |
Common Deployment Pitfalls
- Losing photos on restart — usually a missing or incorrect volume mount. Verify persistence before uploading a large library.
- Port conflicts — if the chosen host port is already in use, the container may start but be unreachable. Change the host port mapping.
- Database not ready — if the stack includes a database, the app may fail on first start if it launches before the database is accepting connections. Restarting the app container after the database is up typically resolves this.
- Metadata not showing — confirm the uploaded file actually contains EXIF/IPTC data; the site states Lychee supports and displays it, but it cannot display what is not in the file.
Adoption Signal
The official site reports 23.9M Docker pulls combined for LinuxServer and LycheeOrg images, alongside 45.9K downloads, 4.3K stars, and 381 forks. These figures indicate a widely used Docker deployment path, which is useful context if you are weighing whether the Docker route is well-trodden.
When Docker Is the Right Choice
Choose the Docker deployment if you want a reproducible, self-contained setup and are comfortable running containers. If you prefer not to manage containers, the site also describes running Lychee on your own server or web space generally, so Docker is one option rather than the only one. For the exact compose contents, environment variables, and current image tags, use the project's Docker Compose Wizard and compose file as the authoritative source.