Add orientation CLI and config documentation
This commit is contained in:
68
docs/cli.md
Normal file
68
docs/cli.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# weatherapi CLI
|
||||
|
||||
## Shortest Useful Command
|
||||
|
||||
```sh
|
||||
go run ./cmd/weatherapi -config config.yml
|
||||
```
|
||||
|
||||
This starts the HTTP API with the supplied YAML configuration. The configured
|
||||
Postgres database must be reachable, and `templates.base_dir` must point to the
|
||||
text response templates when text output is used.
|
||||
|
||||
## Command Overview
|
||||
|
||||
`weatherapi` is the service executable in `cmd/weatherapi`. It loads
|
||||
configuration, opens configured database handles, selects the first configured
|
||||
database as the primary weather data store, registers HTTP endpoints, and starts
|
||||
the feedapi HTTP runtime.
|
||||
|
||||
Build and run a local binary:
|
||||
|
||||
```sh
|
||||
go build -o ./weatherapi ./cmd/weatherapi
|
||||
./weatherapi -config config.yml
|
||||
```
|
||||
|
||||
Run with the default config path:
|
||||
|
||||
```sh
|
||||
./weatherapi
|
||||
```
|
||||
|
||||
## Flag Reference
|
||||
|
||||
| Flag | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `-config` | `WEATHERAPI_CONFIG` when set, otherwise `config.yml` | Path to the YAML config file. |
|
||||
|
||||
`weatherapi` does not currently expose other CLI flags.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| `WEATHERAPI_CONFIG` | Default config path used when `-config` is not provided and the value is not blank. |
|
||||
|
||||
Command-line flags take precedence over environment defaults.
|
||||
|
||||
## Config Path Precedence
|
||||
|
||||
1. `-config /path/to/config.yml`
|
||||
2. non-blank `WEATHERAPI_CONFIG`
|
||||
3. `config.yml` in the current working directory
|
||||
|
||||
## Startup and Shutdown
|
||||
|
||||
Startup fails if configuration cannot be loaded, no database is configured, a
|
||||
configured database cannot be opened, the primary database cannot be selected,
|
||||
or the HTTP app cannot be constructed.
|
||||
|
||||
The process listens for `SIGINT` and `SIGTERM`. When a signal is received, the
|
||||
runtime context is canceled and feedapi performs graceful HTTP shutdown. Database
|
||||
close errors during shutdown are logged.
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [`docs/config.md`](config.md): YAML configuration reference
|
||||
- [`docs/api.md`](api.md): public HTTP API reference
|
||||
130
docs/config.md
Normal file
130
docs/config.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user