Skip to content

Development - Contributing

Issues and pull requests are more than welcome: github.com/sentinel-hub/titiler-openeo/issues

Local environment

It is easiest to bootstrap a development environment with uv:

uv sync
cp .env.eoapi .env
export $(cat .env | xargs)
uvicorn titiler.openeo.main:app --host 0.0.0.0 --port 8081

Pre-commit hooks

This repo is set to use pre-commit to run isort, flake8, pydocstring, black, and mypy when committing new code.

pre-commit install

Running tests

uv run pytest

Add coverage options (e.g. --cov=titiler.openeo) when validating locally before release.

Use the openEO editor

To use the openEO editor, use Docker Compose to start all services:

docker compose up

This will start:

Access the editor at localhost:8080 and set the backend URL to localhost:8081. For authentication setup and testing, see the Admin Guide.

Authentication testing with Keycloak

The project includes a Keycloak instance for testing OpenID Connect authentication. After starting the stack with docker compose up, configure Keycloak as follows:

  1. Access the Keycloak admin console at localhost:8082/admin
  2. Username: admin
  3. Password: admin
  4. Create a new client:
  5. Go to "Clients" → "Create client"
  6. Client ID: titiler-openeo
  7. Client type: OpenID Connect
  8. Click "Next"
  9. Enable "Client authentication"
  10. Enable "Authorization"
  11. Click "Save"
  12. Configure client settings:
  13. Valid redirect URIs: http://localhost:8080/* for the openEO editor
  14. Web origins: http://localhost:8080 for the openEO editor
  15. Click "Save"

The environment includes several pre-configured settings:

  • GDAL optimization settings for performance
  • Debug mode enabled
  • STAC API endpoint set to stac.eoapi.dev

  • Keycloak OIDC configuration

  • Create a test user:

  • Go to "Users" → "Add user"
  • Username: test
  • Email: test@example.com
  • Click "Create"
  • Go to "Credentials" tab
  • Set password: test123
  • Disable "Temporary"
  • Click "Save password"

The Keycloak server will be available at localhost:8082 for testing OIDC authentication flows.

Docs

Install the documentation dependencies (included in the dev group) with uv:

uv sync --group docs

Hot-reloading docs:

mkdocs serve -f docs/mkdocs.yml

To manually deploy docs (note you should never need to do this because GitHub Actions deploys automatically for new commits.):

mkdocs gh-deploy -f docs/mkdocs.yml