Skip to content

Commit b35cf1e

Browse files
alukachalukach
committed
docs: restructure README for environment variable configuration
1 parent 5b03cb3 commit b35cf1e

File tree

1 file changed

+68
-124
lines changed

1 file changed

+68
-124
lines changed

‎README.md‎

Lines changed: 68 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -67,130 +67,74 @@ 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+
72+
| Variable | Description | Type | Required | Default | Example |
73+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- | ---------------- | -------------------------------- |
74+
| `UPSTREAM_URL` | STAC API URL | HTTP(S) URL | Yes | - | `https://your-stac-api.com/stac` |
75+
| `WAIT_FOR_UPSTREAM` | Wait for upstream API to become available before starting proxy | boolean | No | `true` | `false`, `1`, `True` |
76+
| `CHECK_CONFORMANCE` | Ensure upstream API conforms to required conformance classes before starting proxy | boolean | No | `true` | `false`, `1`, `True` |
77+
| `ENABLE_COMPRESSION` | Enable response compression | boolean | No | `true` | `false`, `1`, `True` |
78+
| `HEALTHZ_PREFIX` | Path prefix for health check endpoints | string | No | `/healthz` | `''` (disabled) |
79+
| `OVERRIDE_HOST` | Override the host header for the upstream API | boolean | No | `true` | `false`, `1`, `True` |
80+
| `ROOT_PATH` | Path prefix for the proxy API. **Note:** `ROOT_PATH` is independent of the upstream API's path. The proxy will handle removing this prefix from incoming requests and adding it to outgoing links. | string | No | `''` (root path) | `/api/v1` |
81+
82+
#### Authentication
83+
84+
| Variable | Description | Type | Required | Default | Example |
85+
| --------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------- | ----------------------------------------------------------- |
86+
| `OIDC_DISCOVERY_URL` | OpenID Connect discovery document URL | HTTP(S) URL | Yes | - | `https://auth.example.com/.well-known/openid-configuration` |
87+
| `OIDC_DISCOVERY_INTERNAL_URL` | Internal network OpenID Connect discovery document URL | HTTP(S) URL | No | Value of `OIDC_DISCOVERY_URL` | `http://auth/.well-known/openid-configuration` |
88+
| `DEFAULT_PUBLIC` | Default access policy for endpoints | boolean | No | `false` | `false`, `1`, `True` |
89+
| `PRIVATE_ENDPOINTS` | Endpoints explicitly marked as requiring authentication and possibly scopes | JSON object mapping regex patterns to HTTP methods OR tuples of an HTTP method and string representing required scopes | No | See below | - |
90+
| `PUBLIC_ENDPOINTS` | Endpoints explicitly marked as not requiring authentication, used when `DEFAULT_PUBLIC == False` | JSON object mapping regex patterns to HTTP methods | No | See below | - |
91+
| `ENABLE_AUTHENTICATION_EXTENSION` | Enable authentication extension in STAC API responses | boolean | No | `true` | `false`, `1`, `True` |
92+
93+
**Default `PRIVATE_ENDPOINTS`:**
94+
95+
```json
96+
{
97+
"^/collections$": ["POST"],
98+
"^/collections/([^/]+)$": ["PUT", "PATCH", "DELETE"],
99+
"^/collections/([^/]+)/items$": ["POST"],
100+
"^/collections/([^/]+)/items/([^/]+)$": ["PUT", "PATCH", "DELETE"],
101+
"^/collections/([^/]+)/bulk_items$": ["POST"]
102+
}
103+
```
104+
105+
**Default `PUBLIC_ENDPOINTS`:**
106+
107+
```json
108+
{
109+
"^/api.html$": ["GET"],
110+
"^/api$": ["GET"],
111+
"^/docs/oauth2-redirect": ["GET"],
112+
"^/healthz": ["GET"]
113+
}
114+
```
115+
116+
#### OpenAPI / Swagger UI
117+
118+
| Variable | Description | Type | Required | Default | Example |
119+
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
120+
| `OPENAPI_SPEC_ENDPOINT` | Path of OpenAPI specification, used for augmenting spec response with auth configuration | string or null | No | `null` (disabled) | `/api` |
121+
| `OPENAPI_AUTH_SCHEME_NAME` | Name of the auth scheme to use in the OpenAPI spec | string | No | `oidcAuth` | `jwtAuth` |
122+
| `OPENAPI_AUTH_SCHEME_OVERRIDE` | Override for the auth scheme in the OpenAPI spec | JSON object | No | `null` (disabled) | `{"type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Paste your raw JWT here. This API uses Bearer token authorization.\n"}` |
123+
| `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 | string or null | No | `null` (disabled) | `/api.html` |
124+
| `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 | JSON object | No | `null` (disabled) | `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}` |
125+
126+
#### Filtering
127+
128+
| Variable | Description | Type | Required | Default | Example |
129+
| --------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
130+
| `ITEMS_FILTER_CLS` | CQL2 expression generator for item-level filtering | JSON object with class configuration | No | `null` (disabled) | `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter` |
131+
| `ITEMS_FILTER_ARGS` | Positional arguments for CQL2 expression generator | List of positional arguments used to initialize the class | No | `[]` | `["org1"]` |
132+
| `ITEMS_FILTER_KWARGS` | Keyword arguments for CQL2 expression generator | Dictionary of keyword arguments used to initialize the class | No | `{}` | `{"field_name": "properties.organization"}` |
133+
| `ITEMS_FILTER_PATH` | Regex pattern used to identify request paths that require the application of the items filter | Regex string | No | `^(/collections/([^/]+)/items(/[^/]+)?$\|/search$)` | `^(/collections/([^/]+)/items(/[^/]+)?$\|/search$\|/custom$)` |
134+
| `COLLECTIONS_FILTER_CLS` | CQL2 expression generator for collection-level filtering | JSON object with class configuration | No | `null` (disabled) | `stac_auth_proxy.filters:Opa`, `stac_auth_proxy.filters:Template`, `my_package:OrganizationFilter` |
135+
| `COLLECTIONS_FILTER_ARGS` | Positional arguments for CQL2 expression generator | List of positional arguments used to initialize the class | No | `[]` | `["org1"]` |
136+
| `COLLECTIONS_FILTER_KWARGS` | Keyword arguments for CQL2 expression generator | Dictionary of keyword arguments used to initialize the class | No | `{}` | `{"field_name": "properties.organization"}` |
137+
| `COLLECTIONS_FILTER_PATH` | Regex pattern used to identify request paths that require the application of the collections filter | Regex string | No | `^/collections(/[^/]+)?$` | `^.*?/collections(/[^/]+)?$` |
194138

195139
### Tips
196140

0 commit comments

Comments
 (0)