more fixes

Author: ildyria

docs/faq_troubleshooting.md

@@ -8,6 +8,91 @@ Another way to see this screen is to use the command: `php artisan lychee:diagno
 
 Lychee v7 with FrankenPHP requires a container restart to take into account changes made to the `.env` file.
 
+### My Docker container keeps restarting, what can I do?
+
+If your Lychee Docker container is continuously restarting, the most common cause is a missing or improperly configured `APP_KEY`.
+
+Verify that you have `APP_KEY` properly set in your `.env` file or `docker-compose.yml`. If the key is missing or invalid, you can generate a new one by running:
+
+```bash
+echo "APP_KEY=base64:$(openssl rand -base64 32)"
+```
+
+Copy the generated key and add it to your `.env` file or Docker Compose configuration, then restart the container.
+
+### My workers are not processing jobs, what should I check?
+
+If background job processing is not working in your Docker setup, verify the following settings:
+
+1. Ensure `QUEUE_CONNECTION=database` is set in both the API and worker services
+2. Verify `LYCHEE_MODE=worker` is set in the worker service configuration
+3. Check the worker logs for any errors:
+
+```bash
+docker-compose logs -f lychee_worker
+```
+
+Review the logs for any error messages that might indicate configuration issues or connection problems.
+
+### I'm having upload issues with Docker, what can I do?
+
+Upload problems in Docker deployments are typically related to volume mounting or permissions:
+
+1. Verify that your volume mounts point to the correct paths in your `docker-compose.yml`
+2. Check that file permissions on host directories allow the container user to write
+3. Ensure the uploads directory (typically `./lychee/uploads`) exists on the host and is writable
+
+You can check directory permissions on your host system with:
+
+```bash
+ls -la ./lychee/
+```
+
+If needed, adjust permissions to allow the container to write to the uploads directory.
+
+### I'm experiencing performance issues with Docker, what should I check?
+
+If your Dockerized Lychee instance is running slowly, consider the following:
+
+1. Add worker services for background processing of resource-intensive tasks
+2. Verify FrankenPHP is running correctly (you should see FrankenPHP mentioned in the logs, not nginx)
+3. Ensure `QUEUE_CONNECTION` is set to enable asynchronous job processing
+
+You can check your container logs to verify FrankenPHP is active:
+
+```bash
+docker-compose logs lychee
+```
+
+### I'm getting database connection errors in Docker, what can I do?
+
+Database connection issues in Docker are usually related to service configuration:
+
+1. Ensure the database service name in your `docker-compose.yml` matches the `DB_HOST` value in your configuration
+2. Verify database credentials (`DB_USERNAME`, `DB_PASSWORD`, `DB_DATABASE`) are correct and match between services
+3. Check that the database service is healthy and running:
+
+```bash
+docker-compose ps lychee_db
+```
+
+If the database service shows as unhealthy or restarting, check its logs for more details:
+
+```bash
+docker-compose logs lychee_db
+```
+
+### Since upgrading to Lychee v7, all my thumbnails are missing, what can I do?
+
+After upgrading to Lychee v7, if your thumbnails are missing, you may need to regenerate them. You can do this by running the following Artisan command inside your Lychee container:
+
+```bash
+docker exec -it lychee php artisan lychee:recompute-album-sizes
+docker exec -it lychee php artisan lychee:recompute-album-stats
+```
+
+Or log into the web interface and go to Settings ⇒ Maintenance ⇒ Album Precomputed Fields.
+
 ### 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/upgrade.md

@@ -16,8 +16,14 @@ Version 7 marks a fundamental shift in Lychee's Docker architecture:
 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.
 
+### Port change
+
+Version 7 uses FrankenPHP which listens on port `8000` instead of the previous `80` used by nginx. Make sure to update your port mappings accordingly in your `docker-compose.yml`.
+
 ### Volume Mount Changes
 
+In order to avoid you running into issues while booting version 7, we are blocking the startup of the container if the old volume structure is detected.
+
 #### Version 6 Volume Structure (OLD)
 ```yaml
 volumes:
@@ -32,19 +38,19 @@ volumes:
 ```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
-  - ./conf/user.css:/app/public/dist/user.css # optional
-  - ./conf/custom.js:/app/public/dist/custom.js # optional
+  - ./lychee/conf/.env:/app/.env # OPTIONAL, you can manage your .env directly as variables in docker-compose.yml 
+  - ./lychee/storage/app:/app/storage/app # OPTIONAL: for persistent storage of app data
+  - ./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.
+> {note} Notice the key changes: uploads are now at `/app/public/uploads`, logs at `/app/storage/logs`, tmp at `/app/storage/tmp`, and the `.env` file.
 
 The `/sym` volume has been removed as Lychee no longer uses symbolic links for storage. This was a security feature that originated from version 4, but is no longer necessary as the functionality has been removed.
 
-**Important:** With the 3 volumes under `/app/storage`, you may think you could simplify the configuration by specifying one single volume for `/app/storage` instead. This is incorrect. Doing so will make the app exit with the error "The `/app/bootstrap/cache` directory must be present and writable."
+**Important:** With multiple volumes under `/app/storage`, you may think you could simplify the configuration by specifying one single volume for `/app/storage` instead. This is incorrect. Doing so will make the app exit with the error "The `/app/bootstrap/cache` directory must be present and writable."
 
 ### Service Architecture Changes
 
@@ -235,14 +241,19 @@ docker-compose logs -f lychee
 
 You will notice that after the upgrade, thumbnails are missing. You can regenerate them by running:
 ```bash
-docker exec -it lychee php artisan lychee:backfill-album-fields
+docker exec -it lychee php artisan lychee:recompute-album-sizes
+docker exec -it lychee php artisan lychee:recompute-album-stats
 ```
 
 or by logging into the web interface and going to Settings ⇒ Maintenance ⇒ Album Precomputed Fields.
 
 
 ### Troubleshooting
 
+**Container keeps restarting**
+
+- Verify that you have APP_KEY properly set in your `.env` or `docker-compose.yml` if that is not the case you can run `echo "APP_KEY=base64:$(openssl rand -base64 32)"` to create a new one.
+
 **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