Release 7.0.0 (#258)

Author: ildyria

docs/faq_troubleshooting.md

@@ -4,6 +4,10 @@ If Lychee is not working properly, try to open `https://lychee.example.com/Diagn
 
 Another way to see this screen is to use the command: `php artisan lychee:diagnostics`
 
+### When I update my .env with Lychee v7, the changes are not taken into account, what can I do?
+
+Lychee v7 with FrankenPHP requires a container restart to take into account changes made to the `.env` file.
+
 ### When I do X, I get an error API not found, what can I do?
 
 Open the dev modules of your browser (usually by pressing `F12`) and open the Network tab.

docs/releases.md

@@ -28,6 +28,56 @@
 }
 </style>
 
+## Version 7
+
+### v7.0.0
+
+Released on Dec 31st, 2025
+
+#### IMPORTANT NOTICE: BREAKING CHANGES AHEAD
+
+First and foremost, Version 7 is NOT compatible with php 8.3. The minimum required version is now php 8.4.
+If you are using the release build (with nginx/apache + PHP), please make sure to update your environment accordingly.
+
+Version 7 docker image is now powered by FrankenPHP with Laravel Octane instead of the traditional nginx + PHP-FPM stack. **Upgrading will require you to update your docker-compose setup.**
+
+Check the upgrade documentation for more information: [https://lycheeorg.dev/docs/upgrade.html](https://lycheeorg.dev/docs/upgrade.html)
+
+#### Major release: Webshop, star ratings, and more!
+
+Read more on our [blog post](https://lycheeorg.dev/2025-12-31-version-7/) about Version 7.
+
+#### Most notable changes
+
+`SE` refers to functionalities that are aimed at the Supporter/Pro Edition.  
+`klo` refers to *Keep the Light On*. In other words, basic software updates.  
+
+
+* `klo` #3880 : Spec driven development support by @ildyria.
+* `new` #3881 : Add support for hprof in order to have profiling by @ildyria.
+  > This will help us to profile and optimize Lychee for speed and memory useage..
+* `new` #3879 : Add option to make the smart albums only consider photos of the user by @ildyria.
+* `SE` #3868 : Webshop by @ildyria.
+  > The biggest feature addition of 2025! After 6 months of intensive development, we're proud to introduce our fully-integrated webshop solution.
+* `new` #3889 : Switching to Octane with Frankenphp by @ildyria.
+  > Major architectural change: Our Docker release is now powered by FrankenPHP with Laravel Octane instead of the traditional nginx + PHP-FPM stack.
+* `fix` #3892 : Fix tag-pinned-shared albums not being reset by @ildyria.
+* `new` #3893 : Add avif support by @ildyria.
+  > Add native avif support using the imagick extension.
+* `new` #3896 : Support titles as dates for albums by @ildyria.
+  > If your album is titled with a date format, we will now integrate it in the timeline display.
+* `new` #3898 : PHP 8.3 is dead by @ildyria.
+  > As each year, we drop support for the oldest php version. This year, php8.3 is no longer supported.
+* `SE` #3899 : Add rating per user by @ildyria.
+  > We add ratings per user. Each user can now rate photos from 1 to 5 stars.
+  > Supporters have access to slightly more configurations options.
+* `new` #3903 : feat: add worker mode support for horizontal scaling by @ildyria.
+  > This allows to run Lychee in a horizontally scaled environment with multiple workers.
+  > In other words you can now process images in the background with multiple workers.
+* `new` #3905 : Add pre-computation of thumb images for improved speed by @ildyria.
+  > We now pre-compute the thumb album cover and min-max dates for albums to improve speed when loading albums.
+
+
 ## Version 6
 
 ### v6.10.4
@@ -143,10 +193,6 @@ This means that you will need to update your verification process accordingly. P
 
 #### Most notable changes
 
-`SE` refers to functionalities that are aimed at the Supporter Edition.  
-`klo` refers to *Keep the Light On*. In other words, basic software updates.  
-
-
 * `fix` #3700 : Fix user group issues by @ildyria.
 * `klo` #3701 : Split test suite in hopes to speed things up. by @ildyria.
   > We split the test suite in multiple jobs to speed up the overall test execution time.

docs/upgrade.md

@@ -1,9 +1,270 @@
-## Checking requirements
 
-Check that the server satisfifes the [requirements](installation.html#web-server-configuration). In particular pay attention the PHP extensions.
+
+## Upgrading Lychee docker installations from v6 to v7
+
+> {note} **Critical Breaking Changes**: Version 7 introduces significant architectural changes to the Docker setup. **You must update your docker-compose configuration** when upgrading from v6 to v7. Simply changing the image tag will not work.
+
+### Major Changes in Version 7
+
+Version 7 marks a fundamental shift in Lychee's Docker architecture:
+
+1. **FrankenPHP replaces nginx + PHP-FPM**: The application now runs on FrankenPHP with Laravel Octane for dramatically improved performance
+2. **Simplified volume mounts**: Individual directory mounts have been consolidated into cleaner volume structures
+3. **Optional worker service**: Background job processing can now be scaled independently
+4. **New environment variables**: Worker mode configuration requires specific settings
+
+Do note that this change also has consequences in the way Lychee reads your `.env`
+file. Updating values in the `.env` file will now require a container restart to take effect.
+
+### Volume Mount Changes
+
+#### Version 6 Volume Structure (OLD)
+```yaml
+volumes:
+  - ./lychee/conf:/conf
+  - ./lychee/uploads:/uploads
+  - ./lychee/sym:/sym
+  - ./lychee/logs:/logs
+  - ./lychee/tmp:/lychee-tmp
+```
+
+#### Version 7 Volume Structure (NEW)
+```yaml
+volumes:
+  - ./lychee/uploads:/app/public/uploads
+  - ./lychee/storage/app:/app/storage/app
+  - ./lychee/logs:/app/storage/logs
+  - ./lychee/tmp:/app/storage/tmp  # so that uploads are not filling up the memory of the container
+  - ./lychee/conf/.env:/app/.env:ro
+  - ./conf/user.css:/app/public/dist/user.css # optional
+  - ./conf/custom.js:/app/public/dist/custom.js # optional
+```
+
+> {note} Notice the key changes: uploads are now at `/app/public/uploads`, storage at `/app/storage/app`, tmp at `/app/storage/tmp`, and the `.env` file is mounted read-only.
+
+### Service Architecture Changes
+
+Version 7 introduces a multi-service architecture with an optional worker service for background job processing.
+
+#### Basic Setup (Single Service)
+
+For basic installations without background workers:
+
+```yaml
+services:
+  lychee_api:
+    image: ghcr.io/lycheeorg/lychee:edge
+    container_name: lychee
+    ports:
+      - "${APP_PORT:-8000}:8000"
+    volumes:
+      - ./lychee/uploads:/app/public/uploads
+      - ./lychee/storage/app:/app/storage/app
+      - ./lychee/logs:/app/storage/logs
+      - ./lychee/tmp:/app/storage/tmp
+      - .env:/app/.env:ro
+    environment:
+      - DB_CONNECTION=mysql
+      - DB_HOST=lychee_db
+      - DB_PORT=3306
+      - DB_DATABASE=lychee
+      - DB_USERNAME=lychee
+      - DB_PASSWORD=your_password
+      # ... other environment variables
+    depends_on:
+      - lychee_db
+    networks:
+      - lychee
+```
+
+#### Advanced Setup (With Workers)
+
+For better performance with background job processing:
+
+```yaml
+services:
+  lychee_api:
+    image: ghcr.io/lycheeorg/lychee:edge
+    container_name: lychee
+    ports:
+      - "${APP_PORT:-8000}:8000"
+    volumes:
+      - ./lychee/uploads:/app/public/uploads
+      - ./lychee/storage/app:/app/storage/app
+      - ./lychee/logs:/app/storage/logs
+      - ./lychee/tmp:/app/storage/tmp
+      - .env:/app/.env:ro
+    environment:
+      - DB_CONNECTION=mysql
+      - DB_HOST=lychee_db
+      - QUEUE_CONNECTION=database  # CRITICAL for worker mode
+      # ... other environment variables
+    depends_on:
+      - lychee_db
+    networks:
+      - lychee
+
+  lychee_worker:
+    image: ghcr.io/lycheeorg/lychee:edge
+    container_name: lychee_worker
+    volumes:
+      - ./lychee/uploads:/app/public/uploads
+      - ./lychee/storage/app:/app/storage/app
+      - ./lychee/logs:/app/storage/logs
+      - ./lychee/tmp:/app/storage/tmp
+      - .env:/app/.env:ro
+    environment:
+      - LYCHEE_MODE=worker  # CRITICAL: Tells container to run in worker mode
+      - DB_CONNECTION=mysql
+      - DB_HOST=lychee_db
+      - DB_PORT=3306
+      - DB_DATABASE=lychee
+      - DB_USERNAME=lychee
+      - DB_PASSWORD=your_password
+      - QUEUE_CONNECTION=database  # CRITICAL: Must match API service
+      # ... other environment variables
+    depends_on:
+      - lychee_db
+      - lychee_api
+    networks:
+      - lychee
+```
+
+> {note} **Critical**: When using worker services, you **must** set `QUEUE_CONNECTION=database` (or `redis` if using Redis) in **both** the API and worker services. Without this, jobs will not be processed properly.
+
+### Worker Service Benefits
+
+The worker service provides several advantages:
+
+- **Parallel Processing**: Scale workers independently by running multiple instances
+- **Better Performance**: Offload heavy tasks (photo processing, imports) from the main API
+- **Resource Management**: Allocate different resources to API and workers
+
+#### Scaling Workers
+
+You can run multiple worker instances for parallel processing:
+
+```yaml
+lychee_worker:
+  image: ghcr.io/lycheeorg/lychee:edge
+  deploy:
+    replicas: 3  # Run 3 worker instances
+  # ... rest of configuration
+```
+
+Or manually with different container names:
+
+```yaml
+lychee_worker_1:
+  image: ghcr.io/lycheeorg/lychee:edge
+  container_name: lychee_worker_1
+  environment:
+    - LYCHEE_MODE=worker
+    # ... rest of configuration
+
+lychee_worker_2:
+  image: ghcr.io/lycheeorg/lychee:edge
+  container_name: lychee_worker_2
+  environment:
+    - LYCHEE_MODE=worker
+    # ... rest of configuration
+```
+
+### Migration Steps
+
+Follow these steps to migrate from v6 to v7:
+
+#### 1. **Backup Everything**
+
+```bash
+# Backup your database
+docker exec lychee_db mysqldump -u lychee -p lychee > lychee_backup.sql
+
+# Backup your uploads and configuration
+cp -r ./lychee ./lychee_backup
+```
+
+#### 2. **Stop Your Current v6 Services**
+
+```bash
+docker-compose down
+```
+
+#### 3. **Update Your docker-compose.yml**
+
+Replace your v6 docker-compose.yml with the v7 configuration. You can find the complete example at: [https://github.com/LycheeOrg/Lychee/blob/master/docker-compose.yaml](https://github.com/LycheeOrg/Lychee/blob/master/docker-compose.yaml)
+
+#### 4. **Reorganize Your Volume Data** (if needed)
+
+If your current directory structure doesn't match the new volume mounts, reorganize:
+  
+```bash
+# The uploads directory structure should remain compatible
+# Ensure your uploads are in ./lychee/uploads/
+```
+
+#### 5. **Update Environment Variables**
+
+Key changes to your environment configuration:
+- If using workers: Add `QUEUE_CONNECTION=database` or `QUEUE_CONNECTION=redis`
+- If using workers: Add `LYCHEE_MODE=worker` to worker service only
+- Review other environment variables for any deprecated options
+
+#### 6. **Start v7 Services**
+```bash
+docker-compose up -d
+```
+
+#### 7. **Run Migrations**
+```bash
+docker exec lychee php artisan migrate
+```
+
+#### 8. **Verify Installation**
+
+Check that all services are running:
+```bash
+docker-compose ps
+```
+
+Check logs for errors:
+```bash
+docker-compose logs -f lychee
+```
+
+### Troubleshooting
+
+**Workers not processing jobs**
+- Verify `QUEUE_CONNECTION=database` is set in both API and worker services
+- Verify `LYCHEE_MODE=worker` is set in worker service
+- Check worker logs: `docker-compose logs -f lychee_worker`
+
+**Upload issues**
+- Verify volume mounts point to the correct paths
+- Check file permissions on host directories
+- Ensure uploads directory: `./lychee/uploads` exists and is writable
+
+**Performance issues**
+- Consider adding worker services for background processing
+- Check FrankenPHP is running (should see FrankenPHP in logs, not nginx)
+- Verify `QUEUE_CONNECTION` is set for async job processing
+
+**Database connection errors**
+- Ensure database service name matches `DB_HOST` value
+- Verify database credentials are correct
+- Check database service is healthy: `docker-compose ps lychee_db`
+
+For more help, visit our [GitHub Discussions](https://github.com/LycheeOrg/Lychee/discussions) or [Discord server](https://discord.gg/y4aUbnF).
+
+
+## Upgrading from Lychee v3 to v4
+
+### Checking requirements
+
+Check that the server satisfies the [requirements](installation.html#web-server-configuration). In particular pay attention the PHP extensions.
 You can display installed PHP extensions using `phpinfo()`.
 
-## Preparing the files
+### Preparing the files
 
 Assuming the following tree:
 ```
@@ -32,14 +293,14 @@ mv Lychee-v3/uploads/small/* Lychee/public/uploads/small/
 mv Lychee-v3/uploads/thumb/* Lychee/public/uploads/thumb/
 ```
 
-## Preparing the server
+### Preparing the server
 
 > {note} The big difference between Lychee version 3 and Lychee version 4 is the served directory, i.e. where you webserver needs to point to.
 
 - In the version 3, this was the root `.` of Lychee.
 - In the version 4, this is the `public` directory inside Lychee.
 
-### Using Apache
+#### Using Apache
 
 **Make sure you have the module rewrite available and enabled: `a2enmod rewrite`**.
 
@@ -74,12 +335,10 @@ Restart apache2:
 systemctl restart apache2
 ```
 
-Process with the 
-
-### Using Nginx
+#### Using Nginx
 
 If you are using Nginx, an example configuration can be found [here](installation.html#web-server-configuration).
 
-### Run the migrations
+#### Run the migrations
 
-Make sure you have `DB_OLD_LYCHEE_PREFIX` set in your `.env` to correspond the table prefix of your old database, then run `php artisan migrate`. 
+Make sure you have `DB_OLD_LYCHEE_PREFIX` set in your `.env` to correspond the table prefix of your old database, then run `php artisan migrate`.

gen.py

@@ -48,7 +48,7 @@ def generate_base():
 pages_title['configuration'] = 'Configuration'
 pages_title['docker'] = 'Docker'
 pages_title['update'] = 'Update'
-pages_title['upgrade'] = 'Upgrade from v3'
+pages_title['upgrade'] = 'Upgrade Lychee'
 
 pages_title['settings'] = 'Settings'
 pages_title['keyboard'] = 'Keyboard Shortcuts'