[FEAT] Clarify timezone configuration (TZ vs APP_TIMEZONE vs DISPLAY_TIMEZONE) in README
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 88/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- docker, laravel
- Domain
- documentation
Research direction
Start in readme-vars.yml, reviewing opt_param_env_vars and app_setup_block. Update the timezone variable descriptions and add the three-variable explanation, then verify the README documentation clearly distinguishes TZ, APP_TIMEZONE, and DISPLAY_TIMEZONE and recommends a consistent setting.
Written by the indexing model from the issue text.
Description
Is this a new feature request?
- I have searched the existing issues
Wanted change
Improve the README's documentation around timezone configuration. Speedtest-tracker reads three separate timezone environment variables, and the interaction between them isn't obvious from the current README:
TZ— container OS timezone (cron, system logs)APP_TIMEZONE— Laravel's internal timezone (config/app.php→env('APP_TIMEZONE', 'UTC'))DISPLAY_TIMEZONE— timezone shown in the web UI (config/app.php→env('DISPLAY_TIMEZONE', 'UTC'))
Currently:
APP_TIMEZONEisn't listed inreadme-vars.ymlat all.DISPLAY_TIMEZONEis listed as optional with the description "Timezone for the UI." and no guidance.
Users following the standard LSIO pattern of only setting TZ end up with a UI that displays UTC times regardless of their TZ value, which is a common source of confusion.
Reason for change
This trips up users (myself included) who reasonably expect TZ alone to control displayed times, as it does in most other LSIO images. A short note in Application Setup that all three should generally be set to the same value would save a lot of head-scratching and forum/Discord traffic.
Proposed code change
A small, documentation-only change to readme-vars.yml:
- Add
APP_TIMEZONEtoopt_param_env_vars. - Expand the
DISPLAY_TIMEZONEdescription to recommend matchingTZ. - Add a "Timezone configuration" subsection to
app_setup_blockexplaining the three variables and recommending they all be set to the same value.
--- a/readme-vars.yml
+++ b/readme-vars.yml
@@ -33,13 +33,24 @@ opt_param_env_vars:
- {env_var: "DB_DATABASE", env_value: "", desc: "Database name (postgres/mysql)."}
- {env_var: "DB_USERNAME", env_value: "", desc: "Database username (postgres/mysql)."}
- {env_var: "DB_PASSWORD", env_value: "", desc: "Database password (postgres/mysql)."}
- - {env_var: "DISPLAY_TIMEZONE", env_value: "Etc/UTC", desc: "Timezone for the UI."}
+ - {env_var: "APP_TIMEZONE", env_value: "Etc/UTC", desc: "Timezone Laravel uses internally for scheduling and stored timestamps. Recommended to match `TZ`."}
+ - {env_var: "DISPLAY_TIMEZONE", env_value: "Etc/UTC", desc: "Timezone shown in the web UI. Recommended to match `TZ` so displayed times line up with the container clock."}
- {env_var: "PRUNE_RESULTS_OLDER_THAN", env_value: "0", desc: "Days to keep test results."}
# application setup block
app_setup_block_enabled: true
app_setup_block: |
Access the web UI at `<your-ip>:80`, the default credentials are [email protected] / password
+ ### Timezone configuration
+
+ Speedtest-tracker reads three separate timezone variables and they each control a different layer:
+
+ * `TZ` sets the container OS timezone, used by cron and system logs.
+ * `APP_TIMEZONE` sets the timezone Laravel uses internally for scheduling and stored timestamps.
+ * `DISPLAY_TIMEZONE` sets the timezone shown in the web UI.
+
+ Setting only `TZ` (the common pattern with other LinuxServer.io images) will leave the application and UI on UTC. For consistent behaviour set all three to the same value, e.g. `Europe/London`.
+
For more information check out the [project documentation](https://docs.speedtest-tracker.dev/).
I have this change prepared locally on a branch. Happy to open a PR if you'd like — just wanted to check first since CONTRIBUTING.md asks for an issue rather than a PR for small doc fixes. Let me know which you'd prefer.
- Dominant language
- Dockerfile
- Stars
- 186
- Forks
- 8
- PR merge metrics
- No merged PRs in 30d
Getting set up
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from linuxserver/docker-speedtest-tracker
-
no-issue-activity
Difficulty 4/5 3-5 days Newbie friendliness 38/100
linuxserver/docker-speedtest-tracker#81 · 6 comments ·
-
no-issue-activity
Difficulty 4/5 3-5 days Newbie friendliness 45/100
linuxserver/docker-speedtest-tracker#80 · 4 comments ·
-
no-issue-activity
Difficulty 4/5 3-5 days Newbie friendliness 48/100
linuxserver/docker-speedtest-tracker#79 · 7 comments ·
All issues in linuxserver/docker-speedtest-tracker
Similar issues
-
docs pydanty:is-working
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
pydantic/pydantic-ai#8863 ·
Maintainers usually reply within 1 day
-
documentation from-review-extraction github-actions priority: low severity:nit
Difficulty 1/5 Under an hour Newbie friendliness 92/100
LearningCircuit/local-deep-research#6946 ·
Maintainers usually reply within 1 day
-
enhancement
Difficulty 1/5 Under an hour Newbie friendliness 88/100
esphome/device-builder#2856 ·
Maintainers usually reply within 1 day
-
documentation good first issue
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 1/5 1-3 hours Newbie friendliness 78/100
mantinedev/mantine#9223 ·
Maintainers usually reply within 6 days