Merge branch 'main' into feat/use-eoapi-cdk-v3

Author: vincentsarago

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
           pre-commit run --all-files
 
       - name: Launch services
-        run: docker compose up -d stac raster vector
+        run: docker compose -f docker-compose.custom.yml --profile gunicorn up -d
 
       - name: install lib postgres
         run: |
@@ -67,8 +67,8 @@ jobs:
       # see https://github.com/developmentseed/tipg/issues/37
       - name: Restart the Vector service
         run: |
-          docker compose stop vector
-          docker compose up -d vector
+          docker compose -f docker-compose.custom.yml --profile gunicorn stop vector
+          docker compose -f docker-compose.custom.yml --profile gunicorn up -d vector
 
       - name: Sleep for 10 seconds
         run: sleep 10s
@@ -78,7 +78,7 @@ jobs:
         run: python -m pytest .github/workflows/tests/
 
       - name: Stop services
-        run: docker compose stop
+        run: docker compose -f docker-compose.custom.yml  stop
 
 
   publish-docker:

.github/workflows/deploy_mkdocs.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install mkdocs mkdocs-material pygments
+          python -m pip install -r docs/requirements.txt
 
       - name: Deploy docs
         run: mkdocs gh-deploy --force -f docs/mkdocs.yml

.gitignore

@@ -63,6 +63,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/src/.DS_Store
+docs/src/img/.DS_Store
+docs/src/overrides/.DS_Store
+docs/.DS_Store
 
 # PyBuilder
 target/

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [ 
+    "!ENV scalar",
+    "!ENV sequence",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+  ]
+}

CONTRIBUTING.md

@@ -1,7 +1,7 @@
-# Development - Contributing
-
 Issues and pull requests are more than welcome: https://github.com/developmentseed/eoAPI/issues
 
+You can also start **Discussions** in https://github.com/developmentseed/eoAPI/discussions
+
 **dev install**
 
 ```bash
@@ -19,7 +19,9 @@ python -m pip install "psycopg[binary,pool]"
 python -m pip install -e runtime/eoapi/raster["test"] # or -e runtime/eoapi/stac["test"]  | -e runtime/eoapi/vector["test"]
 ```
 
-Note: services might have incompatible dependencies which you can resolve by using virtual environnement per service
+!!! danger
+
+    Python applications might have incompatible dependencies which you can resolve by using virtual environment *per application*
 
 **pre-commit**
 
@@ -28,3 +30,13 @@ This repo is set to use `pre-commit` to run *isort*, *ruff*, *pydocstring*, *bla
 ```bash
 $ pre-commit install
 ```
+
+### Open Source
+
+You can also contribute indirectly to eoAPI by helping on the sub-modules:
+
+- **PgSTAC** database https://github.com/stac-utils/pgstac
+- **stac-fastapi**: https://github.com/stac-utils/stac-fastapi
+- **titiler-pgstac**:  https://github.com/stac-utils/titiler-pgstac
+- **TiTiler**: https://github.com/developmentseed/titiler
+- **TiPg**: https://github.com/developmentseed/tipg

README.md

@@ -1,7 +1,6 @@
-
 <p align="center">
   <img width="700" src="docs/logos/eoAPI.png"/>
-  <p align="center">Create a full Earth Observation API with Metadata, Raster and Vector services.</p>
+  <p align="center">Create a full Earth Observation API with Metadata, Raster, and Vector services.</p>
 </p>
 
 <p align="center">
@@ -23,7 +22,7 @@
 
 ## **E**arth **O**bservation **API**
 
-`eoAPI` combines several *state-of-the-art* projects to create a full Earth Observation API. Each service can be used and deployed independently but `eoAPI` creates the interconnections between each service:
+`eoAPI` combines several *state-of-the-art* projects to create a full Earth Observation API. Each service can be used and deployed independently, but `eoAPI` creates the interconnections between each service:
 
 - **pgSTAC** database [https://github.com/stac-utils/pgstac](https://github.com/stac-utils/pgstac)
 
@@ -37,52 +36,108 @@
 
 ## 🌍 eoAPI: An Open-Source Community Project
 
-`eoAPI` is proudly open-source and driven by a dedicated community of contributors. We believe in the power of open collaboration and welcome anyone to contribute, discuss, and grow this tool with us. Join the conversations on [GitHub Discussions](https://github.com/developmentseed/eoAPI/discussions) and make a difference in the Earth Observation realm.
+`eoAPI` is proudly open-source and driven by a dedicated community of contributors. We believe in the power of open collaboration and welcome anyone to contribute, discuss, and grow this tool. Join the conversations on [GitHub Discussions](https://github.com/developmentseed/eoAPI/discussions) and make a difference in the Earth Observation realm.
 
 
 ---
 
 ## Getting started
 
-- Clone the repository: `git clone https://github.com/developmentseed/eoAPI.git`
-- Navigate to the project: `cd eoAPI`
-- Run services with `docker compose up`
-- Follow the [MAXAR open data demo](https://github.com/vincentsarago/MAXAR_opendata_to_pgstac) (or get inspired by the other [demos](./demo/)) to load some data into eoAPI
-- Check out the [Search Viewer](http://localhost:8081/index.html), and the API documentation ([STAC Metadata](http://localhost:8081/docs), [Raster Tiles](http://localhost:8082/docs), [Vector Tiles](http://localhost:8083/api.html))
+The easiest way to start exploring the different eoAPI services is with *Docker*. Clone this repository and start the multi-container *Docker* applications using `Compose`:
+
+```
+git clone https://github.com/developmentseed/eoAPI.git
+cd eoAPI
+docker compose up
+```
+
+Once the applications are *up*, you'll need to add STAC **Collections** and **Items** to the PgSTAC database. If you don't have, you can use the follow the [MAXAR open data demo](https://github.com/vincentsarago/MAXAR_opendata_to_pgstac) (or get inspired by the other [demos](https://github.com/developmentseed/eoAPI/tree/main/demo)).
+
+Then you can start exploring your dataset with:
+
+  - the STAC Metadata service [http://localhost:8081](http://localhost:8081)
+  - the Raster service [http://localhost:8082](http://localhost:8082)
+
+If you've added a vector dataset to the `public` schema in the Postgres database, they will be available through the **Vector** service at [http://localhost:8083](http://localhost:8083).
+
+## Deployment
+
+This repository has current runtimes that are consistently updated with new functionality.
+
+The services can be deployed locally via docker with `docker compose up`.
+
+Two Infrastructure as Code (IaC) repositories are available:
+- [eoapi-cdk](https://github.com/developmentseed/eoapi-cdk): A set of AWS CDK constructs to deploy eoAPI services
+- [eoapi-k8s](https://github.com/developmentseed/eoapi-k8s): IaC and Helm charts for deploying eoAPI services on AWS and GCP
+
+Finally, [eoapi-template](https://github.com/developmentseed/eoapi-template) is an AWS CDK app that shows how to configure the eoapi-cdk constructs.
+
+Alternatively, you may install the libraries locally:
+
+<details>
 
-Alternatively, you may launch the application locally:
 ```bash
 python -m pip install --upgrade virtualenv
 virtualenv .venv
 source .venv/bin/activate
 
-python -m pip install "psycopg[binary,pool]" uvicorn
-python -m pip install runtime/eoapi/{SERVICE}  # SERVICE should be one of `raster, vector, stac`
-
 export DATABASE_URL=postgresql://username:[email protected]:5439/postgis  # Connect to the database of your choice
 
-.venv/bin/uvicorn eoapi.{SERVICE}.app:app --port 8000 --reload
+python -m pip install uvicorn
+
+###############################################################################
+# Install and launch the application
+# Select one of the following
+
+###############################################################################
+# STAC
+python -m pip install "psycopg[binary,pool]" stac-fastapi-pgstac
+.venv/bin/uvicorn stac_fastapi.pgstac.app:app --port 8081 --reload
+
+###############################################################################
+# RASTER
+python -m pip install "psycopg[binary,pool]" titiler-pgstac
+.venv/bin/uvicorn titiler.pgstac.main:app --port 8082 --reload
+
+###############################################################################
+# VECTOR
+python -m pip install tipg
+.venv/bin/uvicorn tipg.main:app --port 8083 --reload
 ```
 
-Note: services might have incompatible dependencies which you can resolve by using a virtual environment for each service
+Note: python libraries might have incompatible dependencies, which you can resolve by using a virtual environment for each ones
 
----
+</details>
 
-## Deployment
+## Custom runtimes
 
-This repository has current runtimes that are consistently updated with new functionality. 
+The eoAPI repository hosts customized versions of each base service which can work in parallel or in combination with each other.
 
-The services can be deployed locally via docker with `docker-compose up`. The official runtimes can be launched with `docker-compose -f docker-compose.yml -f docker-compose.official.yml up stac-fastapi titiler-pgstac tipg`. 
+eoAPI custom runtimes can be launched with docker
 
-Two Infrastructure as Code (IaC) repositories are available:
-- [eoapi-cdk](https://github.com/developmentseed/eoapi-cdk): A set of AWS CDK constructs to deploy eoAPI services
-- [eoapi-k8s](https://github.com/developmentseed/eoapi-k8s): IaC and Helm charts for deploying eoAPI services on AWS and GCP
+```
+docker compose -f docker-compose.custom.yml --profile gunicorn up
+```
 
-Finally, [eoapi-template](https://github.com/developmentseed/eoapi-template) is an AWS CDK app that shows how to configure the eoapi-cdk constructs.
+Alternatively, you may launch the application locally:
+```bash
+python -m pip install --upgrade virtualenv
+virtualenv .venv
+source .venv/bin/activate
+
+python -m pip install "psycopg[binary,pool]" uvicorn
+python -m pip install runtime/eoapi/{SERVICE}  # SERVICE should be one of `raster, vector, stac.`
+
+export DATABASE_URL=postgresql://username:[email protected]:5439/postgis  # Connect to the database of your choice
+
+.venv/bin/uvicorn eoapi.{SERVICE}.app:app --port 8000 --reload
+```
+
+Note: services might have incompatible dependencies, which you can resolve by using a virtual environment for each service
 
 ## Contribution & Development
 
-We highly value and rely on our community! Whether you're an expert or just getting started, you can make a difference. Here's how:
+We highly value and rely on our community! You can make a difference whether you're an expert or just getting started. Here's how:
 
 - **Contribute**: Check out our [CONTRIBUTING.md](https://github.com/developmentseed/eoAPI/blob/main/CONTRIBUTING.md) guide to understand how you can contribute.
 - **Engage in Discussions**: Share your ideas, ask questions, or provide feedback through [GitHub Discussions](https://github.com/developmentseed/eoAPI/discussions). This is where most of our project conversations take place.