Posted 19 Jul 2025 in OSS

Setting up a dev env for Lychee

I use Lychee to run pictures.dzombak.com, and I'd like to contribute to it. This is the beauty of open source!

The primary developer, Benoît Viguier, was kind enough to give me some pointers on the dev process, and I'm documenting here how to get a dev environment set up on macOS for Lychee.

Docker

Docker is required. I use OrbStack rather than Docker Desktop.

Node + npm

You'll need npm and a compatible Node version installed. I don't have much to report here since I have this set up already using the asdf version manager + its nodejs plugin. Right now, Node 24.x seems to work.

PHP + Composer

I do not often work with PHP, so I needed to figure out how to get PHP set up on my machine. The path of least resistance seems to be installing PHP with Homebrew and using brew-php-switcher to change versions if necessary.[^1] We'll also install imagemagick via Homebrew and install it for PHP using pecl:

[^1]: I don't love this solution, since PHP version switching will be systemwide, but I'm accepting it for now since this is the only PHP software I'm currently working on.

brew install brew-php-switcher php@8.4 composer imagemagick pkg-config
brew-php-switcher 8.4
pecl install imagick

Build Docker Images

Lychee's dev process relies on two Docker images, lychee-base:latest and lychee-dev:latest. Build both of those:

pushd docker/base && docker build -t lychee-base:latest . && popd
pushd docker/dev && docker build -t lychee-dev:latest . && popd

Backend Setup

composer install
php artisan key:generate
php artisan migrate

Configure `.env`

Run cp .env.example .env. In .env, set:

APP_ENV=dev
APP_URL=http://localhost:90
APP_FORCE_HTTPS=false

Frontend Setup & Build

npm install --include=dev
npm run dev

Run the App

docker-compose up

At this point, Lychee should be accessible at http://localhost:90.

Run Tests

make test_v2
make test_unit

Tests are run locally using an SQLite database, database/database.sqlite.

If tests are failing due to some corrupted or malformed data in the database, you can safely remove database/database.sqlite.

Typechecking, Linting, & Formatting

make formatting
make phpstan
npm run check

You can also run npm run lint, though Benoît notes that there are preexisting failures when running this linter. Still, best to ensure I'm not adding new problems.