titiler-eopf

TiTiler application for EOPF datasets

---

Documentation:

Source Code: https://github.com/EOPF-Explorer/titiler-eopf/

---

Installation

We recommand using uv as project manager for development.

See https://docs.astral.sh/uv/getting-started/installation/ for installation

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, 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 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:

# 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-<commit>
  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:

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):

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:

helm install openeo-eopf . -f /path/to/your/values.yaml

Or install directly from the cloned repository:

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:

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

License

See LICENSE

Authors

See contributors for a listing of individual contributors.

Changes

See CHANGES.md.