Oct 20, 2024 β€’ 3 min read

Lychee: The Full Guide to Self-Hosting Anywhere

Lychee: The Full Guide to Self-Hosting Anywhere

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:

  1. Install Dependencies:

sudo apt update && sudo apt install -y nginx php php-cli php-fpm mariadb-server unzip git

  1. Clone Lychee:

git clone https://github.com/LycheeOrg/Lychee.git /var/www/lychee

cd /var/www/lychee

  1. Set Permissions:

sudo chown -R www-data:www-data /var/www/lychee

sudo chmod -R 755 /var/www/lychee

  1. 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;

  1. 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!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.