Skip to content

Commit 447a13d

Browse files
authored
docs: prefer headings over nested list
1 parent 5b03cb3 commit 447a13d

File tree

1 file changed

+127
-124
lines changed

1 file changed

+127
-124
lines changed

README.md

Lines changed: 127 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -67,130 +67,133 @@ pip install -e .
6767

6868
The application is configurable via environment variables.
6969

70-
- Core
71-
- **`UPSTREAM_URL`**, STAC API URL
72-
- **Type:** HTTP(S) URL
73-
- **Required:** Yes
74-
- **Example:** `https://your-stac-api.com/stac`
75-
- **`WAIT_FOR_UPSTREAM`**, wait for upstream API to become available before starting proxy
76-
- **Type:** boolean
77-
- **Required:** No, defaults to `true`
78-
- **Example:** `false`, `1`, `True`
79-
- **`CHECK_CONFORMANCE`**, ensure upstream API conforms to required conformance classes before starting proxy
80-
- **Type:** boolean
81-
- **Required:** No, defaults to `true`
82-
- **Example:** `false`, `1`, `True`
83-
- **`ENABLE_COMPRESSION`**, enable response compression
84-
- **Type:** boolean
85-
- **Required:** No, defaults to `true`
86-
- **Example:** `false`, `1`, `True`
87-
- **`HEALTHZ_PREFIX`**, path prefix for health check endpoints
88-
- **Type:** string
89-
- **Required:** No, defaults to `/healthz`
90-
- **Example:** `''` (disabled)
91-
- **`OVERRIDE_HOST`**, override the host header for the upstream API
92-
- **Type:** boolean
93-
- **Required:** No, defaults to `true`
94-
- **Example:** `false`, `1`, `True`
95-
- **`ROOT_PATH`**, path prefix for the proxy API
96-
- **Type:** string
97-
- **Required:** No, defaults to `''` (root path)
98-
- **Example:** `/api/v1`
99-
- **Note:** This is independent of the upstream API's path. The proxy will handle removing this prefix from incoming requests and adding it to outgoing links.
100-
- Authentication
101-
- **`OIDC_DISCOVERY_URL`**, OpenID Connect discovery document URL
102-
- **Type:** HTTP(S) URL
103-
- **Required:** Yes
104-
- **Example:** `https://auth.example.com/.well-known/openid-configuration`
105-
- **`OIDC_DISCOVERY_INTERNAL_URL`**, internal network OpenID Connect discovery document URL
106-
- **Type:** HTTP(S) URL
107-
- **Required:** No, defaults to the value of `OIDC_DISCOVERY_URL`
108-
- **Example:** `http://auth/.well-known/openid-configuration`
109-
- **`DEFAULT_PUBLIC`**, default access policy for endpoints
110-
- **Type:** boolean
111-
- **Required:** No, defaults to `false`
112-
- **Example:** `false`, `1`, `True`
113-
- **`PRIVATE_ENDPOINTS`**, endpoints explicitly marked as requiring authentication and possibly scopes
114-
- **Type:** JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes
115-
- **Required:** No, defaults to the following:
116-
```json
117-
{
118-
"^/collections$": ["POST"],
119-
"^/collections/([^/]+)$": ["PUT", "PATCH", "DELETE"],
120-
"^/collections/([^/]+)/items$": ["POST"],
121-
"^/collections/([^/]+)/items/([^/]+)$": ["PUT", "PATCH", "DELETE"],
122-
"^/collections/([^/]+)/bulk_items$": ["POST"]
123-
}
124-
```
125-
- **`PUBLIC_ENDPOINTS`**, endpoints explicitly marked as not requiring authentication, used when `DEFAULT_PUBLIC == False`
126-
- **Type:** JSON object mapping regex patterns to HTTP methods
127-
- **Required:** No, defaults to the following:
128-
```json
129-
{
130-
"^/api.html$": ["GET"],
131-
"^/api$": ["GET"],
132-
"^/docs/oauth2-redirect": ["GET"],
133-
"^/healthz": ["GET"]
134-
}
135-
```
136-
- **`ENABLE_AUTHENTICATION_EXTENSION`**, enable authentication extension in STAC API responses
137-
- **Type:** boolean
138-
- **Required:** No, defaults to `true`
139-
- **Example:** `false`, `1`, `True`
140-
- OpenAPI / Swagger UI
141-
- **`OPENAPI_SPEC_ENDPOINT`**, path of OpenAPI specification, used for augmenting spec response with auth configuration
142-
- **Type:** string or null
143-
- **Required:** No, defaults to `null` (disabled)
144-
- **Example:** `/api`
145-
- **`OPENAPI_AUTH_SCHEME_NAME`**, name of the auth scheme to use in the OpenAPI spec
146-
- **Type:** string
147-
- **Required:** No, defaults to `oidcAuth`
148-
- **Example:** `jwtAuth`
149-
- **`OPENAPI_AUTH_SCHEME_OVERRIDE`**, override for the auth scheme in the OpenAPI spec
150-
- **Type:** JSON object
151-
- **Required:** No, defaults to `null` (disabled)
152-
- **Example:** `{"type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Paste your raw JWT here. This API uses Bearer token authorization.\n"}`
153-
- **`SWAGGER_UI_ENDPOINT`**, path of Swagger UI, used to indicate that a custom Swagger UI should be hosted, typically useful when providing accompanying `SWAGGER_UI_INIT_OAUTH` arguments
154-
- **Type:** string or null
155-
- **Required:** No, defaults to `null` (disabled)
156-
- **Example:** `/api.html`
157-
- **`SWAGGER_UI_INIT_OAUTH`**, initialization options for the [Swagger UI OAuth2 configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/) on custom Swagger UI
158-
- **Type:** JSON object
159-
- **Required:** No, defaults to `null` (disabled)
160-
- **Example:** `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}`
161-
- Filtering
162-
- **`ITEMS_FILTER_CLS`**, CQL2 expression generator for item-level filtering
163-
- **Type:** JSON object with class configuration
164-
- **Required:** No, defaults to `null` (disabled)
165-
- **Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
166-
- **`ITEMS_FILTER_ARGS`**, Positional arguments for CQL2 expression generator
167-
- **Type:** List of positional arguments used to initialize the class
168-
- **Required:** No, defaults to `[]`
169-
- **Example:**: `["org1"]`
170-
- **`ITEMS_FILTER_KWARGS`**, Keyword arguments for CQL2 expression generator
171-
- **Type:** Dictionary of keyword arguments used to initialize the class
172-
- **Required:** No, defaults to `{}`
173-
- **Example:** `{"field_name": "properties.organization"}`
174-
- **`ITEMS_FILTER_PATH`**, Regex pattern used to identify request paths that require the application of the items filter
175-
- **Type:** Regex string
176-
- **Required:** No, defaults to `^(/collections/([^/]+)/items(/[^/]+)?$|/search$)`
177-
- **Example:** `^(/collections/([^/]+)/items(/[^/]+)?$|/search$|/custom$)`
178-
- **`COLLECTIONS_FILTER_CLS`**, CQL2 expression generator for collection-level filtering
179-
- **Type:** JSON object with class configuration
180-
- **Required:** No, defaults to `null` (disabled)
181-
- **Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
182-
- **`COLLECTIONS_FILTER_ARGS`**, Positional arguments for CQL2 expression generator
183-
- **Type:** List of positional arguments used to initialize the class
184-
- **Required:** No, defaults to `[]`
185-
- **Example:**: `["org1"]`
186-
- **`COLLECTIONS_FILTER_KWARGS`**, Keyword arguments for CQL2 expression generator
187-
- **Type:** Dictionary of keyword arguments used to initialize the class
188-
- **Required:** No, defaults to `{}`
189-
- **Example:** `{"field_name": "properties.organization"}`
190-
- **`COLLECTIONS_FILTER_PATH`**, Regex pattern used to identify request paths that require the application of the collections filter
191-
- **Type:** Regex string
192-
- **Required:** No, defaults to `^/collections(/[^/]+)?$`
193-
- **Example:** `^.*?/collections(/[^/]+)?$`
70+
#### Core
71+
- **`UPSTREAM_URL`**, STAC API URL
72+
- **Type:** HTTP(S) URL
73+
- **Required:** Yes
74+
- **Example:** `https://your-stac-api.com/stac`
75+
- **`WAIT_FOR_UPSTREAM`**, wait for upstream API to become available before starting proxy
76+
- **Type:** boolean
77+
- **Required:** No, defaults to `true`
78+
- **Example:** `false`, `1`, `True`
79+
- **`CHECK_CONFORMANCE`**, ensure upstream API conforms to required conformance classes before starting proxy
80+
- **Type:** boolean
81+
- **Required:** No, defaults to `true`
82+
- **Example:** `false`, `1`, `True`
83+
- **`ENABLE_COMPRESSION`**, enable response compression
84+
- **Type:** boolean
85+
- **Required:** No, defaults to `true`
86+
- **Example:** `false`, `1`, `True`
87+
- **`HEALTHZ_PREFIX`**, path prefix for health check endpoints
88+
- **Type:** string
89+
- **Required:** No, defaults to `/healthz`
90+
- **Example:** `''` (disabled)
91+
- **`OVERRIDE_HOST`**, override the host header for the upstream API
92+
- **Type:** boolean
93+
- **Required:** No, defaults to `true`
94+
- **Example:** `false`, `1`, `True`
95+
- **`ROOT_PATH`**, path prefix for the proxy API
96+
- **Type:** string
97+
- **Required:** No, defaults to `''` (root path)
98+
- **Example:** `/api/v1`
99+
- **Note:** This is independent of the upstream API's path. The proxy will handle removing this prefix from incoming requests and adding it to outgoing links.
100+
101+
#### Authentication
102+
- **`OIDC_DISCOVERY_URL`**, OpenID Connect discovery document URL
103+
- **Type:** HTTP(S) URL
104+
- **Required:** Yes
105+
- **Example:** `https://auth.example.com/.well-known/openid-configuration`
106+
- **`OIDC_DISCOVERY_INTERNAL_URL`**, internal network OpenID Connect discovery document URL
107+
- **Type:** HTTP(S) URL
108+
- **Required:** No, defaults to the value of `OIDC_DISCOVERY_URL`
109+
- **Example:** `http://auth/.well-known/openid-configuration`
110+
- **`DEFAULT_PUBLIC`**, default access policy for endpoints
111+
- **Type:** boolean
112+
- **Required:** No, defaults to `false`
113+
- **Example:** `false`, `1`, `True`
114+
- **`PRIVATE_ENDPOINTS`**, endpoints explicitly marked as requiring authentication and possibly scopes
115+
- **Type:** JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes
116+
- **Required:** No, defaults to the following:
117+
```json
118+
{
119+
"^/collections$": ["POST"],
120+
"^/collections/([^/]+)$": ["PUT", "PATCH", "DELETE"],
121+
"^/collections/([^/]+)/items$": ["POST"],
122+
"^/collections/([^/]+)/items/([^/]+)$": ["PUT", "PATCH", "DELETE"],
123+
"^/collections/([^/]+)/bulk_items$": ["POST"]
124+
}
125+
```
126+
- **`PUBLIC_ENDPOINTS`**, endpoints explicitly marked as not requiring authentication, used when `DEFAULT_PUBLIC == False`
127+
- **Type:** JSON object mapping regex patterns to HTTP methods
128+
- **Required:** No, defaults to the following:
129+
```json
130+
{
131+
"^/api.html$": ["GET"],
132+
"^/api$": ["GET"],
133+
"^/docs/oauth2-redirect": ["GET"],
134+
"^/healthz": ["GET"]
135+
}
136+
```
137+
- **`ENABLE_AUTHENTICATION_EXTENSION`**, enable authentication extension in STAC API responses
138+
- **Type:** boolean
139+
- **Required:** No, defaults to `true`
140+
- **Example:** `false`, `1`, `True`
141+
142+
#### OpenAPI / Swagger UI
143+
- **`OPENAPI_SPEC_ENDPOINT`**, path of OpenAPI specification, used for augmenting spec response with auth configuration
144+
- **Type:** string or null
145+
- **Required:** No, defaults to `null` (disabled)
146+
- **Example:** `/api`
147+
- **`OPENAPI_AUTH_SCHEME_NAME`**, name of the auth scheme to use in the OpenAPI spec
148+
- **Type:** string
149+
- **Required:** No, defaults to `oidcAuth`
150+
- **Example:** `jwtAuth`
151+
- **`OPENAPI_AUTH_SCHEME_OVERRIDE`**, override for the auth scheme in the OpenAPI spec
152+
- **Type:** JSON object
153+
- **Required:** No, defaults to `null` (disabled)
154+
- **Example:** `{"type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Paste your raw JWT here. This API uses Bearer token authorization.\n"}`
155+
- **`SWAGGER_UI_ENDPOINT`**, path of Swagger UI, used to indicate that a custom Swagger UI should be hosted, typically useful when providing accompanying `SWAGGER_UI_INIT_OAUTH` arguments
156+
- **Type:** string or null
157+
- **Required:** No, defaults to `null` (disabled)
158+
- **Example:** `/api.html`
159+
- **`SWAGGER_UI_INIT_OAUTH`**, initialization options for the [Swagger UI OAuth2 configuration](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/) on custom Swagger UI
160+
- **Type:** JSON object
161+
- **Required:** No, defaults to `null` (disabled)
162+
- **Example:** `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}`
163+
164+
#### Filtering
165+
- **`ITEMS_FILTER_CLS`**, CQL2 expression generator for item-level filtering
166+
- **Type:** JSON object with class configuration
167+
- **Required:** No, defaults to `null` (disabled)
168+
- **Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
169+
- **`ITEMS_FILTER_ARGS`**, Positional arguments for CQL2 expression generator
170+
- **Type:** List of positional arguments used to initialize the class
171+
- **Required:** No, defaults to `[]`
172+
- **Example:**: `["org1"]`
173+
- **`ITEMS_FILTER_KWARGS`**, Keyword arguments for CQL2 expression generator
174+
- **Type:** Dictionary of keyword arguments used to initialize the class
175+
- **Required:** No, defaults to `{}`
176+
- **Example:** `{"field_name": "properties.organization"}`
177+
- **`ITEMS_FILTER_PATH`**, Regex pattern used to identify request paths that require the application of the items filter
178+
- **Type:** Regex string
179+
- **Required:** No, defaults to `^(/collections/([^/]+)/items(/[^/]+)?$|/search$)`
180+
- **Example:** `^(/collections/([^/]+)/items(/[^/]+)?$|/search$|/custom$)`
181+
- **`COLLECTIONS_FILTER_CLS`**, CQL2 expression generator for collection-level filtering
182+
- **Type:** JSON object with class configuration
183+
- **Required:** No, defaults to `null` (disabled)
184+
- **Example:** `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter`
185+
- **`COLLECTIONS_FILTER_ARGS`**, Positional arguments for CQL2 expression generator
186+
- **Type:** List of positional arguments used to initialize the class
187+
- **Required:** No, defaults to `[]`
188+
- **Example:**: `["org1"]`
189+
- **`COLLECTIONS_FILTER_KWARGS`**, Keyword arguments for CQL2 expression generator
190+
- **Type:** Dictionary of keyword arguments used to initialize the class
191+
- **Required:** No, defaults to `{}`
192+
- **Example:** `{"field_name": "properties.organization"}`
193+
- **`COLLECTIONS_FILTER_PATH`**, Regex pattern used to identify request paths that require the application of the collections filter
194+
- **Type:** Regex string
195+
- **Required:** No, defaults to `^/collections(/[^/]+)?$`
196+
- **Example:** `^.*?/collections(/[^/]+)?$`
194197

195198
### Tips
196199

0 commit comments

Comments
 (0)