# titiler-eopf

TiTiler application for EOPF datasets

Test Coverage License

--- **Documentation**: **Source Code**: https://github.com/EOPF-Explorer/titiler-eopf/ --- ## Installation We recommand using [`uv`](https://docs.astral.sh/uv) as project manager for development. See https://docs.astral.sh/uv/getting-started/installation/ for installation ```bash git clone https://github.com/EOPF-Explorer/titiler-eopf.git cd titiler-eopf uv sync ``` ## Configuration The `titiler-eopf` application is linked to a STAC API. Tiler's endpoints are configured to take `collection_id` and `item_id` path parameter in form of `/collections/{collection_id}/items/{item_id}/...` for individual item access, and `/collections/{collection_id}/...` for collection mosaics. The STAC API is configured with the `TITILER_EOPF_STAC_API_URL` (**required**) environment variable. ``` # Get Dataset Info for `s3://my-bucket/data/sentinel-2/S2A_MSIL2A_20250704T094051_N0511_R036_T33SWB_20250704T115824.zarr` file http://127.0.0.1:8000/collections/sentinel-2/items/S2A_MSIL2A_20250704T094051_N0511_R036_T33SWB_20250704T115824/dataset ``` ## Launch ``` uv run --extra server uvicorn titiler.eopf.main:app --host 127.0.0.1 --port 8080 ``` ### Using Docker ``` git clone https://github.com/EOPF-Explorer/titiler-eopf.git cd titiler-eopf export TITILER_EOPF_STAC_API_URL=https://api.explorer.eopf.copernicus.eu/stac # AWS credentials are required to access assets stored in S3. export AWS_ACCESS_KEY_ID=12345678910 export AWS_SECRET_ACCESS_KEY=a_super_secret_key export AWS_DEFAULT_REGION=somewhere export AWS_ENDPOINT_URL=https://custom_s3_endpoint.dev docker-compose up --build api ``` `http://127.0.0.1:8000/api.html` > Note: `api` and `api-openeo` cannot run at the same time. `api-openeo` extends > `api`, and Compose *merges* the `ports` list rather than replacing it, so > `api-openeo` publishes both 8081 and 8000 and the two collide. Start them one > at a time (`docker compose up api`, then `docker compose up api-openeo`). #### About the image The image is built on [Chainguard Wolfi](https://github.com/wolfi-dev), pinned by digest (`:latest` is the only free Chainguard tag, so the digest is the version pin). GDAL and PROJ come from the `rasterio` and `pyproj` manylinux wheels rather than system packages, so `osgeo` is intentionally absent. The image runs as **root on port 80** — the Helm chart renders `securityContext: {}` and passes `--port 80`, so adding a `USER` directive would crashloop the deployments. The Dockerfile comments explain the rest (why apk versions are unpinned, why `libstdc++` is explicit); `docker/smoke-test.sh` asserts it — see CONTRIBUTING.md. ## OpenEO API Deployment This repository includes a second application that deploys an OpenEO API (`titiler.eopf.openeo.main:app`). The same Docker image built by the CI pipeline can be used to deploy either the TiTiler EOPF application or the OpenEO API by configuring the `MODULE_NAME` environment variable. ### Deploying with Upstream TiTiler-OpenEO Helm Chart The OpenEO API can be deployed using the upstream TiTiler-OpenEO Helm chart from the [sentinel-hub/titiler-openeo](https://github.com/sentinel-hub/titiler-openeo) repository with the Docker image from this repository. #### Prerequisites - Kubernetes cluster with Helm 3.0+ - Docker image from this repository's CI: `ghcr.io/eopf-explorer/titiler-eopf` - Access to the upstream helm chart: https://github.com/sentinel-hub/titiler-openeo/tree/main/deployment/k8s/charts #### Configuration Create a custom `values.yaml` file to override the upstream chart's default image and configure the OpenEO backend: ```yaml # Image configuration - use the image from this repository's CI image: repository: ghcr.io/eopf-explorer/titiler-eopf tag: latest # or specific version tag (e.g., v1.0.0) or sha- pullPolicy: IfNotPresent # IMPORTANT: Override the command to use uvicorn instead of gunicorn # The upstream titiler-openeo chart expects uvicorn, but this image uses gunicorn by default # You must override the command in the deployment configuration command: - "uvicorn" - "titiler.eopf.openeo.main:app" - "--host" - "0.0.0.0" - "--port" - "80" # Alternatively, if the chart doesn't support command override, you can use environment variables # to configure gunicorn (though uvicorn is preferred for compatibility): env: # Application module configuration (for gunicorn - only if you can't override the command) MODULE_NAME: titiler.eopf.openeo.main VARIABLE_NAME: app HOST: 0.0.0.0 PORT: 80 WEB_CONCURRENCY: 1 # STAC Endpoint Configuration TITILER_EOPF_STAC_API_URL: "https://api.explorer.eopf.copernicus.eu/stac/" # OpenEO Backend Configuration (Required) TITILER_OPENEO_STAC_API_URL: "https://api.explorer.eopf.copernicus.eu/stac/" TITILER_OPENEO_STORE_URL: "services/eopf-explorer.json" # AWS Configuration (if using S3) AWS_DEFAULT_REGION: "de" AWS_ENDPOINT_URL: "https://s3.de.io.cloud.ovh.net/" AWS_EC2_METADATA_DISABLED: "true" # OpenEO Authentication Configuration (Optional) TITILER_OPENEO_AUTH_METHOD: "oidc" TITILER_OPENEO_AUTH_OIDC_CLIENT_ID: "cdse-public" TITILER_OPENEO_AUTH_OIDC_WK_URL: "https://identity.dataspace.copernicus.eu/auth/realms/CDSE/.well-known/openid-configuration" TITILER_OPENEO_AUTH_OIDC_REDIRECT_URL: "https://your-openeo-deployment-url/" TITILER_OPENEO_AUTH_OIDC_SCOPES: "openid profile email" TITILER_OPENEO_AUTH_OIDC_NAME_CLAIM: "preferred_username" # Additional OpenEO Configuration (Optional) TITILER_OPENEO_API_DEBUG: "false" TITILER_OPENEO_PROCESSING_MAX_ITEMS: "100" LOG_LEVEL: "INFO" # AWS Credentials - reference to existing secret # (The upstream chart may have different secret handling - adjust as needed) secrets: aws: accessKeyId: "your-access-key-id" secretAccessKey: "your-secret-access-key" ``` #### Installation 1. **Clone the upstream TiTiler-OpenEO repository to access the Helm chart**: ```bash git clone https://github.com/sentinel-hub/titiler-openeo.git cd titiler-openeo/deployment/k8s/charts ``` 2. **Create a Kubernetes secret for AWS credentials** (if using S3): ```bash kubectl create secret generic openeo-aws-credentials \ --from-literal=AWS_ACCESS_KEY_ID=your-access-key-id \ --from-literal=AWS_SECRET_ACCESS_KEY=your-secret-access-key ``` 3. **Install the chart with custom values**: ```bash helm install openeo-eopf . -f /path/to/your/values.yaml ``` Or install directly from the cloned repository: ```bash cd /path/to/titiler-openeo/deployment/k8s/charts helm install openeo-eopf . -f values.yaml ``` #### Local Development For local development, you can run the OpenEO API using the configuration from `.vscode/launch.json`: ```bash export TITILER_OPENEO_STAC_API_URL="https://your-stac-api-url.com" export TITILER_OPENEO_STORE_URL="services/eopf-explorer.json" export TITILER_EOPF_STAC_API_URL="https://api.explorer.eopf.copernicus.eu/stac/" export AWS_DEFAULT_REGION="your-region" export AWS_ENDPOINT_URL="https://your-s3-endpoint.com/" uv run --group server uvicorn titiler.eopf.openeo.main:app --host 127.0.0.1 --port 8081 ``` #### Required Environment Variables The OpenEO API requires the following environment variables to be configured: - `TITILER_OPENEO_STAC_API_URL`: URL of the STAC API for collection discovery - `TITILER_OPENEO_STORE_URL`: Path to the services configuration file - `TITILER_EOPF_STAC_API_URL`: URL of the STAC API endpoint Additional environment variables for authentication, AWS configuration, and other settings can be found in the `.vscode/launch.json` file. ## Contribution & Development See [CONTRIBUTING.md](https://github.com/EOPF-Explorer/titiler-eopf/blob/main/CONTRIBUTING.md) ## License See [LICENSE](https://github.com/EOPF-Explorer/titiler-eopf/blob/main/LICENSE) ## Authors See [contributors](https://github.com/EOPF-Explorer/titiler-eopf/graphs/contributors) for a listing of individual contributors. ## Changes See [CHANGES.md](https://github.com/EOPF-Explorer/titiler-eopf//blob/main/CHANGES.md).