Add configurable timezone support with environment variables
This commit is contained in:
serversdwn
164
TIMEZONE_CONFIGURATION.md
Normal file
164
TIMEZONE_CONFIGURATION.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Timezone Configuration for SLMM
|
||||
|
||||
## Overview
|
||||
|
||||
The SLMM system now supports configurable timezone settings. All timestamps are stored internally in UTC for consistency, but the system can interpret FTP timestamps and display times in your local timezone.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Set the following environment variables to configure your timezone:
|
||||
|
||||
#### `TIMEZONE_OFFSET` (required)
|
||||
The number of hours offset from UTC. Use negative numbers for zones west of UTC, positive for east.
|
||||
|
||||
**Examples:**
|
||||
- `-5` = EST (Eastern Standard Time, UTC-5)
|
||||
- `-4` = EDT (Eastern Daylight Time, UTC-4)
|
||||
- `0` = UTC (Coordinated Universal Time)
|
||||
- `+1` = CET (Central European Time, UTC+1)
|
||||
- `-8` = PST (Pacific Standard Time, UTC-8)
|
||||
|
||||
**Default:** `-5` (EST)
|
||||
|
||||
#### `TIMEZONE_NAME` (optional)
|
||||
A friendly name for your timezone, used in log messages.
|
||||
|
||||
**Examples:**
|
||||
- `EST`
|
||||
- `EDT`
|
||||
- `UTC`
|
||||
- `PST`
|
||||
|
||||
**Default:** Auto-generated from offset (e.g., "UTC-5")
|
||||
|
||||
### Setup Instructions
|
||||
|
||||
#### Option 1: Using .env file (Recommended)
|
||||
|
||||
1. Copy the example file:
|
||||
```bash
|
||||
cd /home/serversdown/slmm
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. Edit `.env` and set your timezone:
|
||||
```bash
|
||||
TIMEZONE_OFFSET=-5
|
||||
TIMEZONE_NAME=EST
|
||||
```
|
||||
|
||||
3. Make sure your application loads the .env file (you may need to install `python-dotenv`):
|
||||
```bash
|
||||
pip install python-dotenv
|
||||
```
|
||||
|
||||
4. Update `app/main.py` to load the .env file (add at the top):
|
||||
```python
|
||||
from dotenv import load_dotenv
|
||||
load_dotenv()
|
||||
```
|
||||
|
||||
#### Option 2: System Environment Variables
|
||||
|
||||
Set the environment variables in your shell or service configuration:
|
||||
|
||||
```bash
|
||||
export TIMEZONE_OFFSET=-5
|
||||
export TIMEZONE_NAME=EST
|
||||
```
|
||||
|
||||
Or add to your systemd service file if running as a service.
|
||||
|
||||
#### Option 3: Docker/Docker Compose
|
||||
|
||||
If using Docker, add to your `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
slmm:
|
||||
environment:
|
||||
- TIMEZONE_OFFSET=-5
|
||||
- TIMEZONE_NAME=EST
|
||||
```
|
||||
|
||||
Or pass via command line:
|
||||
```bash
|
||||
docker run -e TIMEZONE_OFFSET=-5 -e TIMEZONE_NAME=EST ...
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. **FTP Timestamps**: When the system reads file timestamps via FTP from the NL43 device, they are assumed to be in your configured timezone
|
||||
2. **Conversion**: Timestamps are immediately converted to UTC for internal storage
|
||||
3. **Database**: All timestamps in the database are stored in UTC
|
||||
4. **API Responses**: Timestamps are sent to the frontend as UTC ISO strings
|
||||
5. **Frontend Display**: The browser automatically converts UTC timestamps to the user's local timezone for display
|
||||
|
||||
### Example
|
||||
|
||||
If you're in EST (UTC-5) and the FTP shows a file timestamp of "Jan 11 21:57":
|
||||
|
||||
1. System interprets: `Jan 11 21:57 EST`
|
||||
2. Converts to UTC: `Jan 12 02:57 UTC` (adds 5 hours)
|
||||
3. Stores in database: `2026-01-12T02:57:00`
|
||||
4. Sends to frontend: `2026-01-12T02:57:00` (with 'Z' added = UTC)
|
||||
5. Browser displays: `Jan 11, 9:57 PM EST` (converts back to user's local time)
|
||||
|
||||
### Timer Calculation
|
||||
|
||||
The measurement timer calculates elapsed time correctly because:
|
||||
- `measurement_start_time` is stored in UTC
|
||||
- FTP folder timestamps are converted to UTC
|
||||
- Frontend calculates `Date.now() - startTime` using UTC milliseconds
|
||||
- All timezone offsets cancel out, giving accurate elapsed time
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Timer shows wrong elapsed time
|
||||
|
||||
1. **Check your timezone setting**: Make sure `TIMEZONE_OFFSET` matches your actual timezone
|
||||
```bash
|
||||
# Check current setting in logs when SLMM starts:
|
||||
grep "Using timezone" data/slmm.log
|
||||
```
|
||||
|
||||
2. **Verify FTP timestamps**: FTP timestamps from the device should be in your local timezone
|
||||
- If the device is configured for a different timezone, adjust `TIMEZONE_OFFSET` accordingly
|
||||
|
||||
3. **Restart the service**: Changes to environment variables require restarting the SLMM service
|
||||
|
||||
### Logs show unexpected timezone
|
||||
|
||||
Check the startup logs:
|
||||
```bash
|
||||
tail -f data/slmm.log | grep timezone
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
Using timezone: EST (UTC-5)
|
||||
```
|
||||
|
||||
If not, the environment variable may not be loaded correctly.
|
||||
|
||||
## Daylight Saving Time (DST)
|
||||
|
||||
**Important:** This configuration uses a fixed offset. If you need to account for Daylight Saving Time:
|
||||
|
||||
- **During DST (summer)**: Set `TIMEZONE_OFFSET=-4` (EDT)
|
||||
- **During standard time (winter)**: Set `TIMEZONE_OFFSET=-5` (EST)
|
||||
- You'll need to manually update the setting when DST changes (typically March and November)
|
||||
|
||||
**Future Enhancement:** Automatic DST handling could be implemented using Python's `zoneinfo` module with named timezones (e.g., "America/New_York").
|
||||
|
||||
## Default Behavior
|
||||
|
||||
If no environment variables are set:
|
||||
- **TIMEZONE_OFFSET**: Defaults to `-5` (EST)
|
||||
- **TIMEZONE_NAME**: Defaults to `UTC-5`
|
||||
|
||||
This means the system will work correctly for EST deployments out of the box.
|
||||
Reference in New Issue
Block a user