Eric Rakestraw
3ec0a9bd84
All checks were successful
ci/woodpecker/push/build-image Pipeline was successful
133 lines
4.2 KiB
Markdown
133 lines
4.2 KiB
Markdown
# weatherapi Configuration
|
|
|
|
`weatherapi` uses a feedapi YAML config file. This file configures the HTTP
|
|
server, database handles, and text template directory used by the service.
|
|
|
|
## Discovery
|
|
|
|
The executable chooses the config path in this order:
|
|
|
|
1. `-config /path/to/config.yml`
|
|
2. non-blank `WEATHERAPI_CONFIG`
|
|
3. `config.yml`
|
|
|
|
See [`docs/cli.md`](cli.md) for command examples.
|
|
|
|
## Minimal Config
|
|
|
|
```yaml
|
|
server:
|
|
listen_addr: ":8080"
|
|
default_format: json
|
|
|
|
databases:
|
|
- name: weatherdb
|
|
driver: postgres
|
|
uri: postgres://localhost:5432/weatherdb?sslmode=disable
|
|
username: weatherapi
|
|
password: change-me
|
|
|
|
templates:
|
|
base_dir: templates
|
|
```
|
|
|
|
A maintained copy is available at
|
|
[`examples/config.minimal.yml`](../examples/config.minimal.yml).
|
|
|
|
## Production-Oriented Config
|
|
|
|
Use explicit server timeouts, connection pool settings, and secret placeholders
|
|
for production deployments:
|
|
|
|
```yaml
|
|
server:
|
|
listen_addr: ":8080"
|
|
default_format: json
|
|
read_timeout: 5s
|
|
write_timeout: 10s
|
|
idle_timeout: 120s
|
|
|
|
databases:
|
|
- name: weatherdb
|
|
driver: postgres
|
|
uri: postgres://postgres.example.internal:5432/weatherdb?sslmode=require
|
|
username: weatherapi
|
|
password: ${WEATHERAPI_DB_PASSWORD}
|
|
max_open_conns: 10
|
|
max_idle_conns: 5
|
|
conn_max_lifetime: 30m
|
|
conn_max_idle_time: 5m
|
|
|
|
templates:
|
|
base_dir: templates
|
|
```
|
|
|
|
A maintained copy is available at
|
|
[`examples/config.production.yml`](../examples/config.production.yml).
|
|
|
|
## Reference
|
|
|
|
### `server`
|
|
|
|
| Field | Required | Default | Description |
|
|
| --- | --- | --- | --- |
|
|
| `listen_addr` | No | `:8080` | Address passed to the HTTP server. |
|
|
| `default_format` | No | `json` | Response format used when neither `format` nor `Accept` selects one. Supported values are `json`, `xml`, and `text`. |
|
|
| `read_timeout` | No | feedapi default | HTTP server read timeout. |
|
|
| `write_timeout` | No | feedapi default | HTTP server write timeout. |
|
|
| `idle_timeout` | No | feedapi default | HTTP keep-alive idle timeout. |
|
|
|
|
### `databases`
|
|
|
|
`databases` must contain at least one entry. `weatherapi` opens all configured
|
|
databases and uses the first entry as the primary weather data store for all
|
|
implemented reads.
|
|
|
|
| Field | Required | Description |
|
|
| --- | --- | --- |
|
|
| `name` | Yes | Database handle name. The first configured name is selected as primary by `cmd/weatherapi`. |
|
|
| `driver` | Yes | Database driver. The implemented deployment uses `postgres`. |
|
|
| `uri` | Yes | PostgreSQL connection URI. |
|
|
| `username` | Yes | Database username. |
|
|
| `password` | Yes | Database password. Use secret injection in real deployments. |
|
|
| `max_open_conns` | No | Maximum open connections for the database pool. |
|
|
| `max_idle_conns` | No | Maximum idle connections for the database pool. |
|
|
| `conn_max_lifetime` | No | Maximum lifetime for pooled connections. |
|
|
| `conn_max_idle_time` | No | Maximum idle time for pooled connections. |
|
|
|
|
The database must already contain the weatherfeeder-owned tables read by
|
|
`weatherapi`. This service does not ingest weather data and does not create or
|
|
migrate those tables.
|
|
|
|
### `templates`
|
|
|
|
| Field | Required | Description |
|
|
| --- | --- | --- |
|
|
| `base_dir` | Yes | Directory containing the `*.txt.tmpl` files used for text responses. |
|
|
|
|
The repository includes templates under [`templates/`](../templates/). The
|
|
Docker image copies this directory to `/weatherapi/templates` and runs with
|
|
`/weatherapi` as the working directory.
|
|
|
|
## Validation and Defaults
|
|
|
|
Configuration is loaded by feedapi. `cmd/weatherapi` adds one local validation
|
|
rule: at least one database entry is required.
|
|
|
|
Documented server defaults come from feedapi. Unknown YAML fields are not
|
|
documented as rejected by `weatherapi`; treat unrecognized fields as unsupported
|
|
configuration.
|
|
|
|
## Secrets
|
|
|
|
Do not commit production passwords, tokens, private hostnames, or private
|
|
connection strings. The examples use placeholders. Inject real values through
|
|
your deployment tooling before starting the service.
|
|
|
|
## Related Docs
|
|
|
|
- [`docs/cli.md`](cli.md): command-line usage and config path precedence
|
|
- [`docs/api.md`](api.md): HTTP format negotiation and API behavior
|
|
- [`docs/operations.md`](operations.md): deployment and runtime guidance
|
|
- [`docs/integrations/feedapi.md`](integrations/feedapi.md): feedapi config and runtime boundaries
|