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!
