127 lines
2.7 KiB
Markdown
127 lines
2.7 KiB
Markdown
# wttr
|
|
|
|
Weather forecast service written in Zig, based on [wttr.in](https://wttr.in).
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Build
|
|
zig build
|
|
|
|
# Run with defaults
|
|
./zig-out/bin/wttr
|
|
|
|
# With custom configuration
|
|
WTTR_LISTEN_PORT=8080 ./zig-out/bin/wttr
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Weather for your location (based on IP)
|
|
curl localhost:8002/
|
|
|
|
# Weather for a specific city
|
|
curl localhost:8002/London
|
|
|
|
# Weather for coordinates
|
|
curl localhost:8002/51.5074,-0.1278
|
|
|
|
# One-line format
|
|
curl localhost:8002/London?format=3
|
|
|
|
# JSON output
|
|
curl localhost:8002/London?format=j1
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is via environment variables:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `WTTR_LISTEN_HOST` | `0.0.0.0` | Listen address |
|
|
| `WTTR_LISTEN_PORT` | `8002` | Listen port |
|
|
| `WTTR_CACHE_DIR` | `~/.cache/wttr` | Cache directory |
|
|
| `WTTR_CACHE_SIZE` | `10000` | Max cached responses |
|
|
| `WTTR_GEOLITE_PATH` | `~/.cache/wttr/GeoLite2-City.mmdb` | GeoIP database path |
|
|
| `IP2LOCATION_API_KEY` | (none) | Optional IP geolocation fallback |
|
|
|
|
## External Services
|
|
|
|
### Required (No API Key)
|
|
- **Met.no Weather API** - Weather data provider (free, no registration)
|
|
|
|
### Optional
|
|
- **IP2Location.io** - Fallback IP geolocation
|
|
- Sign up at https://www.ip2location.io/
|
|
- Free tier: 30,000 requests/month
|
|
- Set via `IP2LOCATION_API_KEY` environment variable
|
|
|
|
### Auto-Downloaded
|
|
- **MaxMind GeoLite2 City** - IP geolocation database
|
|
- Downloaded automatically if missing
|
|
- Stored in `~/.cache/wttr/GeoLite2-City.mmdb`
|
|
|
|
## Output Formats
|
|
|
|
- **ANSI** (default) - Colored terminal output
|
|
- **Line formats** (`?format=1-4`) - One-line weather
|
|
- **JSON** (`?format=j1`) - Machine-readable
|
|
- **v2** (`?format=v2`) - Data-rich format
|
|
- **Custom** (`?format=%l:+%c+%t`) - Custom format string
|
|
|
|
## Query Parameters
|
|
|
|
- `?u` - Imperial units (°F, mph)
|
|
- `?m` - Metric units (°C, km/h)
|
|
- `?format=N` - Output format
|
|
- `?lang=XX` - Language (auto-detected by default)
|
|
|
|
## Building
|
|
|
|
```bash
|
|
# Debug build
|
|
zig build
|
|
|
|
# Release build
|
|
zig build -Doptimize=ReleaseFast
|
|
|
|
# Run tests
|
|
zig build test
|
|
```
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
# Build image
|
|
docker build -t wttr -f docker/Dockerfile .
|
|
|
|
# Run container
|
|
docker run -p 8002:8002 wttr
|
|
```
|
|
|
|
## Prometheus Integration
|
|
|
|
**Note:** Not yet implemented - see [MISSING_FEATURES.md](MISSING_FEATURES.md)
|
|
|
|
```yaml
|
|
# prometheus.yml
|
|
scrape_configs:
|
|
- job_name: 'weather'
|
|
static_configs:
|
|
- targets: ['localhost:8002']
|
|
metrics_path: '/London'
|
|
params:
|
|
format: ['p1']
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture and design
|
|
- [API_ENDPOINTS.md](API_ENDPOINTS.md) - Complete API reference
|
|
- [MISSING_FEATURES.md](MISSING_FEATURES.md) - Features not yet implemented
|
|
|
|
## License
|
|
|
|
See [LICENSE](LICENSE)
|