You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/upgrade.md
+251-1Lines changed: 251 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -82,4 +82,254 @@ If you are using Nginx, an example configuration can be found [here](installatio
82
82
83
83
### Run the migrations
84
84
85
-
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`.
85
+
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`.
86
+
87
+
## Upgrading from Lychee v6 to v7
88
+
89
+
> {danger} **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.
90
+
91
+
### Major Changes in v7
92
+
93
+
Version 7 marks a fundamental shift in Lychee's Docker architecture:
94
+
95
+
1.**FrankenPHP replaces nginx + PHP-FPM**: The application now runs on FrankenPHP with Laravel Octane for dramatically improved performance
96
+
2.**Simplified volume mounts**: Individual directory mounts have been consolidated into cleaner volume structures
97
+
3.**Optional worker service**: Background job processing can now be scaled independently
98
+
4.**New environment variables**: Worker mode configuration requires specific settings
99
+
100
+
### Volume Mount Changes
101
+
102
+
#### v6 Volume Structure (OLD)
103
+
```yaml
104
+
volumes:
105
+
- ./lychee/conf:/conf
106
+
- ./lychee/uploads:/uploads
107
+
- ./lychee/sym:/sym
108
+
- ./lychee/logs:/logs
109
+
- ./lychee/tmp:/lychee-tmp
110
+
```
111
+
112
+
#### v7 Volume Structure (NEW)
113
+
```yaml
114
+
volumes:
115
+
- ./lychee/uploads:/app/public/uploads
116
+
- ./lychee/storage/app:/app/storage/app
117
+
- ./lychee/logs:/app/storage/logs
118
+
- ./lychee/tmp:/app/storage/tmp # so that uploads are not filling up the memory of the container
> {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 with the optionals .
125
+
126
+
### Service Architecture Changes
127
+
128
+
Version 7 introduces a multi-service architecture with an optional worker service for background job processing.
129
+
130
+
#### Basic Setup (Single Service)
131
+
132
+
For basic installations without background workers:
133
+
134
+
```yaml
135
+
services:
136
+
lychee_api:
137
+
image: ghcr.io/lycheeorg/lychee:edge
138
+
container_name: lychee
139
+
ports:
140
+
- "${APP_PORT:-8000}:8000"
141
+
volumes:
142
+
- ./lychee/uploads:/app/public/uploads
143
+
- ./lychee/storage/app:/app/storage/app
144
+
- ./lychee/logs:/app/storage/logs
145
+
- ./lychee/tmp:/app/storage/tmp
146
+
- .env:/app/.env:ro
147
+
environment:
148
+
- DB_CONNECTION=mysql
149
+
- DB_HOST=lychee_db
150
+
- DB_PORT=3306
151
+
- DB_DATABASE=lychee
152
+
- DB_USERNAME=lychee
153
+
- DB_PASSWORD=your_password
154
+
# ... other environment variables
155
+
depends_on:
156
+
- lychee_db
157
+
networks:
158
+
- lychee
159
+
```
160
+
161
+
#### Advanced Setup (With Workers)
162
+
163
+
For better performance with background job processing:
164
+
165
+
```yaml
166
+
services:
167
+
lychee_api:
168
+
image: ghcr.io/lycheeorg/lychee:edge
169
+
container_name: lychee
170
+
ports:
171
+
- "${APP_PORT:-8000}:8000"
172
+
volumes:
173
+
- ./lychee/uploads:/app/public/uploads
174
+
- ./lychee/storage/app:/app/storage/app
175
+
- ./lychee/logs:/app/storage/logs
176
+
- ./lychee/tmp:/app/storage/tmp
177
+
- .env:/app/.env:ro
178
+
environment:
179
+
- DB_CONNECTION=mysql
180
+
- DB_HOST=lychee_db
181
+
- QUEUE_CONNECTION=database # CRITICAL for worker mode
182
+
# ... other environment variables
183
+
depends_on:
184
+
- lychee_db
185
+
networks:
186
+
- lychee
187
+
188
+
lychee_worker:
189
+
image: ghcr.io/lycheeorg/lychee:edge
190
+
container_name: lychee_worker
191
+
volumes:
192
+
- ./lychee/uploads:/app/public/uploads
193
+
- ./lychee/storage/app:/app/storage/app
194
+
- ./lychee/logs:/app/storage/logs
195
+
- ./lychee/tmp:/app/storage/tmp
196
+
- .env:/app/.env:ro
197
+
environment:
198
+
- LYCHEE_MODE=worker # CRITICAL: Tells container to run in worker mode
199
+
- DB_CONNECTION=mysql
200
+
- DB_HOST=lychee_db
201
+
- DB_PORT=3306
202
+
- DB_DATABASE=lychee
203
+
- DB_USERNAME=lychee
204
+
- DB_PASSWORD=your_password
205
+
- QUEUE_CONNECTION=database # CRITICAL: Must match API service
206
+
# ... other environment variables
207
+
depends_on:
208
+
- lychee_db
209
+
- lychee_api
210
+
networks:
211
+
- lychee
212
+
```
213
+
214
+
> {danger} **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.
215
+
216
+
### Worker Service Benefits
217
+
218
+
The worker service provides several advantages:
219
+
220
+
- **Parallel Processing**: Scale workers independently by running multiple instances
221
+
- **Better Performance**: Offload heavy tasks (photo processing, imports) from the main API
222
+
- **Resource Management**: Allocate different resources to API and workers
223
+
224
+
#### Scaling Workers
225
+
226
+
You can run multiple worker instances for parallel processing:
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)
275
+
276
+
4. **Reorganize Your Volume Data** (if needed)
277
+
278
+
If your current directory structure doesn't match the new volume mounts, reorganize:
279
+
```bash
280
+
# The uploads directory structure should remain compatible
281
+
# Ensure your uploads are in ./lychee/uploads/
282
+
```
283
+
284
+
5. **Update Environment Variables**
285
+
286
+
Key changes to your environment configuration:
287
+
- If using workers: Add `QUEUE_CONNECTION=database` or `QUEUE_CONNECTION=redis`
288
+
- If using workers: Add `LYCHEE_MODE=worker` to worker service only
289
+
- Review other environment variables for any deprecated options
290
+
291
+
6. **Start v7 Services**
292
+
```bash
293
+
docker-compose up -d
294
+
```
295
+
296
+
7. **Run Migrations**
297
+
```bash
298
+
docker exec lychee php artisan migrate
299
+
```
300
+
301
+
8. **Verify Installation**
302
+
303
+
Check that all services are running:
304
+
```bash
305
+
docker-compose ps
306
+
```
307
+
308
+
Check logs for errors:
309
+
```bash
310
+
docker-compose logs -f lychee
311
+
```
312
+
313
+
### Troubleshooting
314
+
315
+
**Workers not processing jobs**
316
+
- Verify `QUEUE_CONNECTION=database` is set in both API and worker services
317
+
- Verify `LYCHEE_MODE=worker` is set in worker service
Copy file name to clipboardExpand all lines: src/content/post/2025-12-31-version-7.mdx
+46-8Lines changed: 46 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,16 +13,54 @@ tags:
13
13
- Rating
14
14
---
15
15
16
+
## 2025: A Year of Innovation and Growth for Lychee
16
17
17
-
Frankenphp docker image for faster runtime performance.
18
-
Support of assymetric processing for faster import.
19
-
Refactoring to improve loading speed of large albums.
20
-
Adding star rating capabilities to Lychee.
21
-
User can select a rating from 1 to 5 stars for each photo.
18
+
As we close out 2025, we're thrilled to celebrate another milestone year for Lychee! Our journey this year has been marked by significant technical achievements, expanded functionality, and a deepened commitment to our community. Throughout the year, we've shipped an impressive 41 releases packed with new features, performance improvements, and important security fixes. From introducing Flow (a social-friendly feed-like display) and Timeline views to adding powerful tools like watermarking, zip upload support, and the Renamer module, we've continuously enhanced what Lychee can do for photographers.
22
19
23
-
Introducing Lychee Pro - Webshop - 6 months of work to build a full webshop solution. Available for our supporter of 10$/month or more.
24
-
Granted to all our existing supporters as a thank you for their support.
25
-
Webshop features: processing payments (Mollie, Paypal & Offline), managing products, handling orders, and more.
20
+
We welcomed a new reviewer, [@JasonMillward](https://github.com/JasonMillward), who has been instrumental in maintaining code quality and ensuring that every release meets our high standards. We also had the pleasure of welcoming new contributor [@cdzombak](https://github.com/cdzombak), who brought fantastic UX improvements including pinned albums, embedded galleries with video support, and numerous usability enhancements.
21
+
22
+
Security remained a priority with multiple SSRF vulnerability fixes, ensuring your self-hosted gallery stays safe. The foundation we built through tags refactoring, user groups, Flow and Sync improvements, and multiple admin support has culminated in our most ambitious release yet: Version 7.
23
+
24
+
### Version 7: Our Most Ambitious Release Yet
25
+
26
+
Version 7 marks a major architectural shift for Lychee. Our Docker release is now powered by FrankenPHP with Laravel Octane instead of the traditional nginx + PHP-FPM stack. This infrastructure keeps the framework in memory and reuses components across requests, eliminating the overhead of rebuilding the entire application on every page load. As a result, boot time drops from 40-60ms to just 4-6ms per request, with 3-4x better throughput and significantly reduced latency.
27
+
28
+
In May 2025, FrankenPHP gained official support from the PHP Foundation, cementing its position as the future of high-performance PHP applications.
29
+
30
+
The new FrankenPHP-powered Docker image is available at `ghcr.io/lycheeorg/lychee:edge` and will become the default once version 7 is fully stable.
31
+
32
+
This architectural change means you will need to update your Docker setup when upgrading from version 6 to version 7 with FrankenPHP. Please refer to our [upgrade documentation](https://lycheeorg.github.io/docs/upgrading-from-lychee-v6-to-v7) for detailed instructions.
33
+
34
+
#### Performance Revolution
35
+
36
+
In addition to changing the PHP engine, we've implemented several key performance optimizations:
37
+
38
+
-**Asymmetric Processing**: Intelligent parallel processing for photo imports, slashing the time needed to upload and process large photo collections
39
+
-**Album Loading Optimization**: Deep refactoring of our codebase to handle large albums with grace, ensuring smooth browsing even with thousands of photos
40
+
41
+
#### New Features That Matter
42
+
43
+
**Star Rating System**: We listened to your feedback! Users can now rate their photos from 1 to 5 stars. In the future, we will be adding smart albums related to ratings, filters, and more. Whether you're a professional photographer curating a portfolio or simply want to mark your favorites, this feature puts powerful organization tools at your fingertips to showcase your best work.
44
+
45
+
**Webshop**: The biggest feature addition of 2025! After 6 months of intensive development, we're proud to introduce our fully-integrated webshop solution. This game-changing feature enables photographers to:
46
+
- Sell prints, digital downloads, and photo products directly through Lychee
47
+
- Process payments seamlessly via Mollie, PayPal, or offline methods
48
+
- Manage product catalogs
49
+
- Handle orders from creation through fulfillment
50
+
51
+
The Webshop empowers photographers to monetize their work without leaving their Lychee galleries, opening new revenue streams and simplifying the sales process. This feature is exclusive to Lychee Pro users.
52
+
53
+
As a thank you to our loyal supporters, we've granted Lychee Pro access to all existing supporters at the $10/month tier or higher. This is our way of recognizing the community that makes Lychee possible.
54
+
55
+
### Looking Ahead
56
+
57
+
The innovations in Version 7 lay the groundwork for even more exciting developments. Our commitment remains unchanged: building the best self-hosted photo management/portfolio solution while respecting your privacy and giving you complete control over your images.
58
+
59
+
Thank you to everyone who contributed to making 2025 such an extraordinary year for Lychee. Here's to another year of innovation, community, and beautiful photography!
60
+
61
+
---
62
+
63
+
**Ready to upgrade?** Visit our documentation to learn how to update to Version 7 and start experiencing these improvements today.
0 commit comments