Advanced Setups

Introduction

In this page we describe additional ways to install and potentially to develop on Lychee.

Separating Data from the Code

As described in issue #486, LudovicRousseau proposes a solution to separate your photos from the Lychee code.

He splits Lychee itself and the pictures into 2 directories: - Lychee with the code of Lychee - Lychee-data containing:

Lychee-data/
└── public
    ├── dist
    │   ├── fonts
    │   └── resources
    └── uploads
        ├── big
        ├── import
        ├── medium
        ├── raw
        ├── small
        └── thumb

• his Lychee/.env contains:

LYCHEE_DIST="/var/www/Lychee-data/public/dist/"
LYCHEE_UPLOADS="/var/www/Lychee-data/public/uploads/"

{note} Note that the path needs to be absolute.

The upgrade script when a new version of Lychee is available is simple:

mv Lychee Lychee.old
unzip Lychee.zip
cp Lychee.old/.env Lychee
chmod g+w -R Lychee/storage
sudo chgrp www-data -R Lychee/storage
cd Lychee
php artisan key:generate
php artisan migrate

It worked fine with the migration from 4.0.4 to 4.0.5 of Lychee.

The hierarchy Lychee-data/public/ is writeable by the group www-data so that apache process can modify the files. The files in Lychee are read only for apache. No write access needed.

VirtualBox with Visual Studio Code

• Requires an Apache server with proxy and proxy_http enabled.
• Requires a Virtual Machine (using e.g. VirtualBox)

Set Up & Port Forwarding

Set up your VM as if you would install any server.

Set up the following port forwarding:

• host:10180 ↠ guest:80
• host:10122 ↠ guest:22

The first one will allow us to access the server from Local host, the second will allow us to connect to it via SSH.

Apache and Proxy in the Host

Edit your /etc/hosts to contain:

127.0.0.1   lychee.test
127.0.0.1   lycheeorg.test

Create configuration files in /etc/apache2/sites-available: 001-lychee-test.conf and 002-lycheeorg-test.conf

<VirtualHost *:80>
    ServerName lychee.test

    ProxyPass / http://localhost:10180/
    ProxyPassReverse / http://lychee.test/
    ProxyPreserveHost On
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

and

<VirtualHost *:80>
    ServerName lycheeorg.test

    ProxyPass / http://localhost:10180/
    ProxyPassReverse / http://lycheeorg.test/
    ProxyPreserveHost On
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Enable the sites and reload apache:

sudo a2ensite 001-lychee-test.conf
sudo a2ensite 002-lycheeorg-test.conf
sudo systemctl restart apache2

Apache in the Guest

In your guest OS, clone the Lychee repository (requires ssh key to be set up):

git clone git@github.com:LycheeOrg/Lychee.git /var/www/html/Lychee
git clone git@github.con:LycheeOrg/LycheeOrg.github.io /var/www/html/LycheeOrg.github.io

Similarily in /etc/apache2/sites-available create 2 configuration files: 001-lychee.conf and 002-lycheeorg.conf

<VirtualHost *:80>
    ServerName lychee.test

    DocumentRoot /var/www/html/Lychee/public

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

and

<VirtualHost *:80>
    ServerName lycheeorg.test

    DocumentRoot /var/www/html/LycheeOrg.github.io

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Enable the sites and reload apache:

sudo a2ensite 001-lychee-test.conf
sudo a2ensite 002-lycheeorg-test.conf
sudo systemctl restart apache2

Open a browser on your host and navigate to http://lychee.test and http://lycheeorg.test enjoy.

Visual Studio Code

If you use Visual Studio Code, you can use the remote ssh extension. It will allow you to directly edit your files in your VM without having to upload and download the files.

Other means of distributions

In this section we present few out-of-the-box solutions providing Lychee.

{note} Please note that we, at LycheeOrg, do not endorse any of the following solutions. We give the reader a link to their websites as they provide our software. You are free to use their installation, however we will not be providing you support with their solution.

With Linuxserver.io (Free)

Linuxserver.io is a group of like minded enthusiasts from across the world who build and maintain the largest collection of Docker images on the web, and at our core are the principles behind Free and Open Source Software. Their primary goal is to provide easy-to-use and streamlined Docker images with clear and concise documentation.

You can find the corresponding Lychee image here.

With Yunohost (Free)

Yunohost is a simple operating system for self-hosting your applications. Lychee is available from their app store and can be installed by clicking this installation link. You can find the source code of the app under https://github.com/YunoHost-Apps/lychee_ynh.

With Cloudron (Paid)

Cloudron is a complete solution for running apps on your server and keeping them up-to-date and secure.

The source code for the package can be found here.

See their pricing here.

With alwaysdata (Paid)

alwaysdata.com is a modern hosting platform allowing you to host all your services in one place: files, emails, sites, media, databases, workers, etc.

You can use their Marketplace to install Lychee and have your own instance available (with HTTPS) within a minute!

See their pricing here.

With Kubernetes (Free)

You can use a Community maintained Helmchart to deploy Lychee into your Kubernetes Cluster.

Have a look at the Repository for installation instructions.

Feel free to open an Issue if you need help.

With Portainer on Synology (Free~ish)

Marius Bogdan Lixandru made a great post of how to set up your Lychee installation on your Synology NAS with Portainer. Read at it here.

Implementing Object Storage

An S3-compatible object storage solution is designed to store, manage, and access unstructured data in the cloud.

Under Object Storage, files (also called objects) are stored in flat data structures (referred to as buckets) alongside their own rich metadata.

Due to the nature of Object Storage, it does not require the use of a Compute Instance. Instead, Object Storage gives each object a unique URL with which you can access the data.

Limitations

• Upload file size limit: 5 GB
• All recursive tasks including (search, find, ls, etc.) have poor performance due to network latency

S3 Object Storage Setup

The instructions in this guide are based on CentOS/Fedora/RHEL family, but it is easy to replicate the commands into any other distro.

Install s3fs FUSE-base file system

s3fs allows Linux and other OS's to mount an S3 bucket via FUSE (Filesystem in Userspace).

s3fs makes you operate files and directories in S3 bucket like a local file system.

s3fs-fuse - Instructions from developer

sudo dnf install s3fs-fuse
sudo echo ACCESS_KEY_ID:SECRET_ACCESS_KEY > /etc/passwd-s3fs
sudo chmod 600 /etc/passwd-s3fs

Configure SELinux to allow access to the new filesystem

setsebool -P httpd_use_fusefs 1

Setup a permanent mounting point

Create S3 Object mount point:

sudo mkdir /mnt/bucket

Edit fstab to create a new mount on boot:
Add the following line to: /etc/fstab

<bucket> /mnt/bucket fuse.s3fs _netdev, allow_other, enable_noobj_cache, url=<s3_endpoint>, use_cache="", passwd_file=/etc/passwd-s3fs, mp_umask=0002 0 0

Example:

• mybucket (name used in your cloud provider)
• https://eu-central-1.linodeobjects.com

Parameters are explained below:

• allow_other Allow other users to access the bucket
• mp_umask Mask permissions for mount point
• enable_noobj_cache Performance improvement - Enable when bucket is exclusively used by s3fs
• use_cache="" Disabled
• use_cache=/var/cache/s3fs Enabled (to be used with care, because the cache can grow out of control. Also, I haven't noticed much difference using it)

Reboot your server to confirm S3 Object Storage is mounted correctly.
Create Lychee's mount point:

sudo mkdir /mnt/bucket/uploads

Create and run Lychee container

From now on, Lychee will see the Object Storage mount transparently like any other mount.
The container's volume /uploads needs to point to the new created mount:

sudo podman run --rm -d --name myphotos -v /mnt/bucket/uploads:/uploads -e PUID=33 -e PGID=1000 ... docker.io/lycheeorg/lychee

Configure .ENV

To avoid latency when clicking Diagnostics, my suggestion is to disable BasicPermissionCheck. Otherwise, depending on the number of photos in your gallery, this task can take hours.

# /var/lib/containers/storage/volumes/lychee-conf/_data/.env
SKIP_DIAGNOSTICS_CHECKS=BasicPermissionCheck

Limitations to be considered

As explained before, recursive tasks are penalised in Object Storage, so if you have an existing bucket and the container runs for the first time, it will take long time to review and set the permissions in your mount. Depending on the number of photos, it can take several hours.

Hosting Lychee in a subpath with Apache

To serve Lychee in a subpath, e.g. https://my.url/photos/, we can use Apaches's Alias-directive.

In this example we assume the web root to be located at /var/www/html, the web user and group to be www-data, and install from the master branch.

Before getting started, make sure your system qualifies the Server Requirements.

Setup Lychee

Clone the repository to outside the web root, e.g. /var/www/:

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

Set the file ownership and permissions:

sudo chown -R www-data:www-data /var/www/Lychee
sudo chmod -R 2775 /var/www/Lychee

Install composer in /var/www/Lychee as instructed in here. Then, from /var/www/Lychee, install the project dependencies:

sudo -u www-data php composer.phar install --no-dev

Setup Apache

Link https://my.url/photos/ to /var/www/Lychee/public by adding the following to your Apache configuration for Aliases. In Apache 2.4 running on Debian, the correct configuration file is /etc/apache2/mods-available/alias.conf.

Alias /photos /var/www/Lychee/public

<Directory /var/www/Lychee/public>
   Options FollowSymLinks
   AllowOverride All
   Require all granted
</Directory>

Finally, restart Apache:

sudo service apache2 restart

Configure Lychee

At this point, you should be able to go to https://my.url/photos/ and run the web installer. During the installation procedure, on top of adding the database credentials to match your setup, set your APP_URL to the served subdirectory:

APP_URL=https://my.url/photos/

Done!