diff --git a/.gitignore b/.gitignore index 07c8e00c..6a2bce2f 100644 --- a/.gitignore +++ b/.gitignore @@ -160,4 +160,4 @@ cython_debug/ # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ -.pgdata \ No newline at end of file +.pgdata diff --git a/README.md b/README.md index f6c6dc58..bd040475 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ STAC Auth Proxy is a proxy API that mediates between the client and your internally accessible STAC API to provide flexible authentication, authorization, and content-filtering mechanisms. > [!IMPORTANT] +> > **We would :heart: to hear from you!** > Please [join the discussion](https://github.com/developmentseed/eoAPI/discussions/209) and let us know how you're using eoAPI! This helps us improve the project for you and others. > If you prefer to remain anonymous, you can email us at eoapi@developmentseed.org, and we'll be happy to post a summary on your behalf. @@ -25,7 +26,9 @@ STAC Auth Proxy is a proxy API that mediates between the client and your interna ### Running -The simplest way to run the project is by invoking the application via Docker: +#### Docker + +The simplest way to run the project is via Docker: ```sh docker run \ @@ -36,31 +39,42 @@ docker run \ ghcr.io/developmentseed/stac-auth-proxy:latest ``` -Alternatively, the module can be invoked directly or the application's factory can be passed to Uvicorn: +#### Python + +The installed Python module can be invoked directly: ```sh python -m stac_auth_proxy ``` +#### Uvicorn + +The application's factory can be passed to Uvicorn: + ```sh uvicorn --factory stac_auth_proxy:create_app ``` -### Docker compose +#### Docker Compose + +The codebase ships with a `docker-compose.yaml` file, allowing the proxy to be run locally alongside various supporting services: the database, the STAC API, and a Mock OIDC provider. + +##### pgSTAC Backend -Run all of the services required to run the application locally including the the database, STAC API, and Mock OICD provider using Docker compose. +Run the application stack with a pgSTAC backend using [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac): -Spin up the application stack with the pgSTAC backend using [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac): ```sh -UPSTREAM_URL=http://stac-pg:8001 docker compose --profile pg up +docker compose up ``` -and with the OpenSearch backend using [stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch): +##### OpenSearch Backend + +Run the application stack with an OpenSearch backend using [stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch): + ```sh -UPSTREAM_URL=http://stac-os:8001 docker compose --profile os up +docker compose --profile os up ``` - ### Installation For local development, we use [`uv`](https://docs.astral.sh/uv/) to manage project dependencies and environment. @@ -83,6 +97,7 @@ pip install -e . The application is configurable via environment variables. #### Core + - **`UPSTREAM_URL`**, STAC API URL - **Type:** HTTP(S) URL - **Required:** Yes @@ -114,6 +129,7 @@ The application is configurable via environment variables. - **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. #### Authentication + - **`OIDC_DISCOVERY_URL`**, OpenID Connect discovery document URL - **Type:** HTTP(S) URL - **Required:** Yes @@ -155,6 +171,7 @@ The application is configurable via environment variables. - **Example:** `false`, `1`, `True` #### OpenAPI / Swagger UI + - **`OPENAPI_SPEC_ENDPOINT`**, path of OpenAPI specification, used for augmenting spec response with auth configuration - **Type:** string or null - **Required:** No, defaults to `null` (disabled) @@ -177,6 +194,7 @@ The application is configurable via environment variables. - **Example:** `{"clientId": "stac-auth-proxy", "usePkceWithAuthorizationCodeGrant": true}` #### Filtering + - **`ITEMS_FILTER_CLS`**, CQL2 expression generator for item-level filtering - **Type:** JSON object with class configuration - **Required:** No, defaults to `null` (disabled) diff --git a/docker-compose.yaml b/docker-compose.yaml index 98b169cf..867cadb8 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,25 +1,21 @@ services: stac-pg: - profiles: ["pg"] + profiles: [""] # default profile image: ghcr.io/stac-utils/stac-fastapi-pgstac:5.0.2 environment: APP_HOST: 0.0.0.0 APP_PORT: 8001 RELOAD: true - ENVIRONMENT: local POSTGRES_USER: username POSTGRES_PASS: password POSTGRES_DBNAME: postgis POSTGRES_HOST_READER: database-pg POSTGRES_HOST_WRITER: database-pg POSTGRES_PORT: 5432 - WEB_CONCURRENCY: 10 - VSI_CACHE: TRUE - GDAL_HTTP_MERGE_CONSECUTIVE_RANGES: YES - GDAL_DISABLE_READDIR_ON_OPEN: EMPTY_DIR DB_MIN_CONN_SIZE: 1 DB_MAX_CONN_SIZE: 1 USE_API_HYDRATE: ${USE_API_HYDRATE:-false} + hostname: stac ports: - "8001:8001" depends_on: @@ -30,9 +26,8 @@ services: profiles: ["os"] container_name: stac-fastapi-os image: ghcr.io/stac-utils/stac-fastapi-os:v6.1.0 - hostname: stac-os environment: - STAC_FASTAPI_TITLEL: stac-fastapi-opensearch + STAC_FASTAPI_TITLE: stac-fastapi-opensearch STAC_FASTAPI_DESCRIPTION: A STAC FastAPI with an Opensearch backend STAC_FASTAPI_VERSION: 6.0.0 STAC_FASTAPI_LANDING_PAGE_ID: stac-fastapi-opensearch @@ -40,22 +35,22 @@ services: APP_PORT: 8001 RELOAD: true ENVIRONMENT: local - WEB_CONCURRENCY: 10 ES_HOST: database-os ES_PORT: 9200 ES_USE_SSL: false ES_VERIFY_CERTS: false BACKEND: opensearch STAC_FASTAPI_RATE_LIMIT: 200/minute + hostname: stac ports: - "8001:8001" depends_on: - database-os - command: + command: | bash -c "./scripts/wait-for-it-es.sh database-os:9200 && python -m stac_fastapi.opensearch.app" database-pg: - profiles: ["pg"] + profiles: [""] # default profile container_name: database-pg image: ghcr.io/stac-utils/pgstac:v0.9.5 environment: @@ -88,13 +83,12 @@ services: - "9200:9200" proxy: - profiles: ["pg", "os"] depends_on: - oidc build: context: . environment: - UPSTREAM_URL: ${UPSTREAM_URL:-http://stac-pg:8001} + UPSTREAM_URL: ${UPSTREAM_URL:-http://stac:8001} OIDC_DISCOVERY_URL: ${OIDC_DISCOVERY_URL:-http://localhost:8888/.well-known/openid-configuration} OIDC_DISCOVERY_INTERNAL_URL: ${OIDC_DISCOVERY_INTERNAL_URL:-http://oidc:8888/.well-known/openid-configuration} env_file: @@ -106,7 +100,6 @@ services: - ./src:/app/src oidc: - profiles: ["pg", "os"] image: ghcr.io/alukach/mock-oidc-server:latest environment: ISSUER: http://localhost:8888