Lychee is a powerful, self-hosted photo management application that provides an intuitive and customizable interface for organizing and sharing your image collection. Designed for tech-savvy users, it offers complete control over your data, making it an excellent choice for privacy-conscious individuals and organizations. This guide provides hands-on steps for deploying, configuring, and managing Lychee, covering everything from installation to leveraging its advanced features.
Installing Lychee
π¦ Docker/Docker Compose Setup
The preferred method for deploying Lychee is using Docker Compose, which simplifies container management. Create a docker-compose.yml
file with the following command:
nano docker-compose.yml
Paste the following configuration into the file:
version: '3.3'
services:
lychee:
image: lycheeorg/lychee:latest
container_name: lychee
ports:
- "8080:80" # Map port 8080 on the host to port 80 in the container
volumes:
- ./uploads:/var/www/html/uploads # Store uploaded images
- ./sym:/var/www/html/sym
- ./logs:/var/www/html/logs # Store application logs
- ./config:/var/www/html/config # Store app configuration
environment:
- PHP_TZ=UTC # Set timezone
- DB_CONNECTION=mysql # Database connection type
- DB_HOST=db # Database container's hostname
- DB_PORT=3306 # Database port
- DB_DATABASE=lychee # Database name
- DB_USERNAME=lychee_user # Database user
- DB_PASSWORD=secure_password # Database password
db:
image: mariadb:latest
container_name: lychee_db
restart: always
environment:
MYSQL_ROOT_PASSWORD=root_password
MYSQL_DATABASE=lychee
MYSQL_USER=lychee_user
MYSQL_PASSWORD=secure_password
volumes:
- ./db:/var/lib/mysql
Deploy the container using:
docker-compose up -d
π Manual Installation
For users deploying Lychee directly on a Linux server, follow these steps:
- Install Dependencies:
sudo apt update && sudo apt install -y nginx php php-cli php-fpm mariadb-server unzip git
- Clone Lychee:
git clone https://github.com/LycheeOrg/Lychee.git /var/www/lychee
cd /var/www/lychee
- Set Permissions:
sudo chown -R www-data:www-data /var/www/lychee
sudo chmod -R 755 /var/www/lychee
- Configure Database:
sudo mysql -u root -p
CREATE DATABASE lychee;
CREATE USER 'lychee_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON lychee.* TO 'lychee_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
- Complete Setup:
Point your browser to http://<server-ip>
and follow the Lychee installation wizard.
Configuring Nginx as a Reverse Proxy
π Nginx Configuration
Set up an Nginx server block for Lychee to route traffic. Edit the file:
sudo nano /etc/nginx/sites-available/lychee
Add the following configuration:
server {
listen 80;
server_name yourdomain.com;
root /var/www/lychee/;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~ /\.ht {
deny all;
}
}
Enable the configuration and restart Nginx:
sudo ln -s /etc/nginx/sites-available/lychee /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
π SSL/TLS Setup
Secure your Lychee instance using Let's Encrypt. Install Certbot and generate certificates:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
Test automatic SSL renewal:
sudo certbot renew --dry-run
π οΈ Testing and Reloading Nginx
Verify the configuration and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Lychee
ποΈ Enabling Debug Logs
To enable verbose logging, edit Lycheeβs .env
file (or environment variables if using Docker):
nano /path_to_lychee/.env
Set the following:
APP_DEBUG=true
π Viewing Logs
If running Lychee via Docker, view logs using:
docker logs lychee
For manual installations, check logs in:
tail -f /var/www/lychee/logs/*
π οΈ Troubleshooting Common Issues
Check common errors like database connection problems. Example fix for missing database credentials:
nano /var/www/lychee/.env
Ensure the following are correctly set:
DB_HOST=localhost
DB_DATABASE=lychee
DB_USERNAME=lychee_user
DB_PASSWORD=secure_password
π€ Exporting Logs
To send logs to an external system (e.g., ELK Stack), configure Filebeat
or similar tools to monitor Lycheeβs log directory.
Backup and Restore
ποΈ File-Based Backups
Backup Lycheeβs key files:
tar -czvf lychee_backup_$(date +%F).tar.gz /var/www/lychee/
π Database Backups
Export the database:
mysqldump -u lychee_user -p lychee > lychee_db_backup.sql
Restore the database:
mysql -u lychee_user -p lychee < lychee_db_backup.sql
π Automated Backup Scripts
Create a cron job for periodic backups:
crontab -e
Add the following line:
0 2 * * * /usr/bin/mysqldump -u lychee_user -p'password' lychee > /path/to/backups/lychee_db_$(date +\%F).sql
Updating and Upgrading Lychee
β¬οΈ Updating Docker Images
Pull the latest image and redeploy:
docker-compose pull
docker-compose up -d
π οΈ Manual Updates
For manual installations, pull the latest changes:
cd /var/www/lychee
git pull origin master
π Checking for Updates
Review Lycheeβs GitHub repository or documentation for patch notes and update availability.
Leveraging Lycheeβs Unique Features
π§ Enabling APIs
Enable the API by ensuring the API option is active in the .env
file:
LYCHEE_API_ENABLED=true
Example API usage with curl
:
curl -X POST -H "Content-Type: application/json" -d '{"username":"admin", "password":"password"}' http://yourdomain.com/api/session
π Advanced Configurations
Customize Lychee by editing configuration options in /var/www/lychee/.env
. For example, to set a custom upload limit:
UPLOAD_MAX_FILESIZE=20M
Wrapping Up
This guide covered the complete lifecycle of deploying, configuring, and managing Lychee, from installation to leveraging its unique features. By self-hosting Lychee, you gain complete control over your photo management workflow, ensuring privacy and flexibility. Start implementing these steps to enjoy a powerful, self-hosted photo management solution tailored to your needs!