140 lines
4.9 KiB
Markdown
140 lines
4.9 KiB
Markdown
# Cache Configuration
|
|
|
|
wttr.in uses three separate caches following Linux Filesystem Hierarchy Standard (FHS) and XDG Base Directory specifications.
|
|
|
|
## External Services
|
|
|
|
### Required Services
|
|
- **Met.no Weather API** - Primary weather data provider
|
|
- No API key required
|
|
- Free, open API from Norwegian Meteorological Institute
|
|
- Rate limit: Be respectful, use caching
|
|
|
|
### Optional Services
|
|
- **IP2Location.io** - Fallback IP geolocation service
|
|
- API key required: Sign up at https://www.ip2location.io/
|
|
- Used when MaxMind GeoIP database lookup fails
|
|
- Free tier: 30,000 requests/month
|
|
- Set via `IP2LOCATION_API_KEY` environment variable
|
|
|
|
### Database Files
|
|
- **MaxMind GeoLite2 City** - IP geolocation database
|
|
- Free database, auto-downloaded if missing
|
|
- No API key required for database usage
|
|
- Updates available monthly from MaxMind
|
|
|
|
## Cache Locations
|
|
|
|
All caches default to `$XDG_CACHE_HOME/wttr` (typically `~/.cache/wttr`).
|
|
|
|
### 1. Weather Response Cache
|
|
**Purpose:** Caches weather API responses to reduce upstream requests
|
|
|
|
**Default Location:** `$XDG_CACHE_HOME/wttr/` (individual files)
|
|
**Environment Variable:** `WTTR_CACHE_DIR`
|
|
**Size:** 10,000 entries (configurable via `WTTR_CACHE_SIZE`)
|
|
**Expiration:** 1000-2000 seconds (16-33 minutes, randomized to avoid thundering herd)
|
|
**Eviction:** LRU (Least Recently Used)
|
|
|
|
This is the main cache that stores weather forecast responses from Met.no. Each entry has a randomized TTL to prevent cache stampedes.
|
|
|
|
### 2. Geocoding Cache (Optional)
|
|
**Purpose:** Caches location name → coordinates mappings
|
|
|
|
**Default:** Disabled (in-memory only)
|
|
**Environment Variable:** `WTTR_GEOCACHE_FILE`
|
|
**Format:** JSON
|
|
**Expiration:** None (persists indefinitely)
|
|
**Eviction:** None (grows unbounded)
|
|
|
|
When enabled, persists geocoding lookups to disk. Saves every 15 minutes if dirty. Useful for reducing external geocoding API calls.
|
|
|
|
### 3. IP2Location Cache
|
|
**Purpose:** Caches IP → coordinates from IP2Location API
|
|
|
|
**Default Location:** `$XDG_CACHE_HOME/wttr/ip2location.cache`
|
|
**Environment Variable:** `IP2LOCATION_CACHE_FILE`
|
|
**Format:** Binary (32-byte records)
|
|
**Expiration:** None (persists indefinitely)
|
|
**Eviction:** None (append-only, grows unbounded)
|
|
|
|
Only used when `IP2LOCATION_API_KEY` is configured. Provides fallback when MaxMind GeoIP database lookup fails.
|
|
|
|
## GeoIP Database Location
|
|
|
|
**Default:** `$XDG_CACHE_HOME/wttr/GeoLite2-City.mmdb`
|
|
**Environment Variable:** `WTTR_GEOLITE_PATH`
|
|
|
|
This is the MaxMind GeoLite2 database. It will be automatically downloaded if missing.
|
|
|
|
## Environment Variables Summary
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `WTTR_CACHE_DIR` | `$XDG_CACHE_HOME/wttr` | Weather response cache directory |
|
|
| `WTTR_CACHE_SIZE` | `10000` | Maximum number of cached weather responses |
|
|
| `WTTR_GEOCACHE_FILE` | (none) | Optional persistent geocoding cache file |
|
|
| `WTTR_GEOLITE_PATH` | `$XDG_CACHE_HOME/wttr/GeoLite2-City.mmdb` | MaxMind GeoLite2 database path |
|
|
| `IP2LOCATION_API_KEY` | (none) | API key for IP2Location fallback service |
|
|
| `IP2LOCATION_CACHE_FILE` | `$XDG_CACHE_HOME/wttr/ip2location.cache` | IP2Location cache file |
|
|
| `XDG_CACHE_HOME` | `~/.cache` | XDG base cache directory |
|
|
|
|
## Examples
|
|
|
|
### Minimal Configuration (defaults)
|
|
```bash
|
|
./wttr
|
|
# Uses ~/.cache/wttr/ for all caches and GeoIP database
|
|
```
|
|
|
|
### Custom Cache Location
|
|
```bash
|
|
WTTR_CACHE_DIR=/var/cache/wttr ./wttr
|
|
# All caches and GeoIP in /var/cache/wttr/
|
|
```
|
|
|
|
### Enable Persistent Geocoding Cache
|
|
```bash
|
|
WTTR_GEOCACHE_FILE=~/.cache/wttr/geocache.json ./wttr
|
|
```
|
|
|
|
### With IP2Location Fallback
|
|
```bash
|
|
IP2LOCATION_API_KEY=your_key_here ./wttr
|
|
# Cache at ~/.cache/wttr/ip2location.cache
|
|
```
|
|
|
|
### Production Setup
|
|
```bash
|
|
WTTR_CACHE_DIR=/var/cache/wttr \
|
|
WTTR_CACHE_SIZE=50000 \
|
|
WTTR_GEOCACHE_FILE=/var/cache/wttr/geocache.json \
|
|
IP2LOCATION_API_KEY=your_key_here \
|
|
./wttr
|
|
# GeoIP and IP2Location cache also in /var/cache/wttr/
|
|
```
|
|
|
|
## Cache Maintenance
|
|
|
|
### Weather Cache
|
|
- **Automatic expiration:** Entries expire after 16-33 minutes (randomized)
|
|
- **LRU eviction:** When cache reaches max size (10,000 entries), least recently used entries are removed
|
|
- **Disk cleanup:** Expired files are cleaned up on access
|
|
- Safe to delete entire cache directory; will be recreated as needed
|
|
|
|
### Geocoding Cache
|
|
- **No expiration:** Entries persist indefinitely
|
|
- **No eviction:** Cache grows unbounded
|
|
- **Auto-save:** Writes to disk every 15 minutes when modified
|
|
- Consider periodic cleanup if cache grows too large
|
|
|
|
### IP2Location Cache
|
|
- **No expiration:** Entries persist indefinitely
|
|
- **Append-only:** File grows unbounded (32 bytes per unique IP)
|
|
- **No cleanup:** Consider periodic truncation for long-running deployments
|
|
- Safe to delete; will be recreated on next API lookup
|
|
|
|
### GeoIP Database
|
|
- **Manual updates:** Download new database periodically for accuracy
|
|
- **Auto-download:** Database is automatically downloaded if missing on startup
|
|
- Typical update frequency: monthly (MaxMind releases)
|