From 3b272dfb528d7a8df94dc2e44fafec89fd52da94 Mon Sep 17 00:00:00 2001 From: Darko Gjorgjijoski Date: Mon, 21 Sep 2026 18:51:02 +0200 Subject: [PATCH] docs: correct the scheduler guidance for Docker The recurring invoices page told Docker users that cron was handled for them "on version 5.0.0 by default", which was never true of any InvoiceShelf image: none of them ran a scheduler, so recurring invoices were never created and this page was the reason nobody investigated. Current images supervise the scheduler themselves. Documents that, names the SCHEDULER_ENABLED escape hatch, and adds the option for hosts that can run neither a crontab nor a long-running process: the cron webhook, its CRON_JOB_AUTH_TOKEN secret and the header it expects, which were undocumented. --- docs/guide/recurring-invoices.md | 31 ++++++++++++++++++++++++++++++- docs/install/docker.md | 14 ++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/docs/guide/recurring-invoices.md b/docs/guide/recurring-invoices.md index 999774c..d81fc94 100644 --- a/docs/guide/recurring-invoices.md +++ b/docs/guide/recurring-invoices.md @@ -46,7 +46,16 @@ In order for InvoiceShelf to automatically create Invoices on a given schedule, #### For Docker: -InvoiceShelf includes support for cron with docker on version 5.0.0 by default. If you're updating from a previous version, please take a backup of your database + files and re-run `docker-compose up`. +The InvoiceShelf image runs the scheduler itself, as a supervised service +alongside the web server, so a container install needs no cron of its own. + +If your recurring invoices have never been created, update to a current image: +earlier images shipped no scheduler at all, and nothing on this page ran. + +Set `SCHEDULER_ENABLED=false` only if you drive the schedule from somewhere +else, such as a second container running +`php artisan schedule:work` or more than one replica of the web container. +Leave it unset otherwise. #### Other Providers: @@ -62,6 +71,26 @@ Example command for a shared hosting provider like Godaddy: /usr/local/bin/php /home/myuser/public_html/InvoiceShelf/artisan schedule:run >> /dev/null 2>&1 ``` +#### Hosts With No Cron At All: + +Some shared hosts allow neither a crontab entry nor a long-running process. For +those, InvoiceShelf can be driven over HTTP: set a secret in your `.env` + +``` +CRON_JOB_AUTH_TOKEN=a-long-random-string +``` + +and have any external scheduler call the endpoint below once a minute, sending +the secret in the `x-authorization-token` header. + +``` +curl -H "x-authorization-token: a-long-random-string" https://your-invoiceshelf/api/cron +``` + +The endpoint refuses every caller while the token is unset, so it is inert +unless you deliberately turn it on. Calling it more often than once a minute is +harmless: extra calls answer `{"success": true, "ran": false}` and do nothing. + #### Testing Locally: Run the below command if you would like to test recurring invoices on your local machine. (Note: This command does not work on windows) diff --git a/docs/install/docker.md b/docs/install/docker.md index 6e9118c..36d87b5 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -131,3 +131,17 @@ services in `docker-compose.yml` before making the installation public. Select SQLite and leave the database path unchanged: `/var/www/html/storage/app/database.sqlite`. + +## Scheduled work + +The container runs Laravel's scheduler itself, supervised alongside the web +server. That is what creates recurring invoices, flags invoices overdue and +expires estimates, so there is no crontab to add on the host. + +Set `SCHEDULER_ENABLED=false` only if you drive the schedule from elsewhere, +for example a second container started with +`command: ["php", "/var/www/html/artisan", "schedule:work"]`, or if you run more +than one replica of the web container and want exactly one of them scheduling. + +See [Recurring Invoices](../guide/recurring-invoices.md#server-configuration) +for the options open to hosts that can run neither.