# 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