weatherapi/docs/config.md

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 for command examples.

Minimal Config

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.

Production-Oriented Config

Use explicit server timeouts, connection pool settings, and secret placeholders for production deployments:

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.

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/. 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: command-line usage and config path precedence
• docs/api.md: HTTP format negotiation and API behavior
• docs/operations.md: deployment and runtime guidance
• docs/integrations/feedapi.md: feedapi config and runtime boundaries