diff --git a/CHANGELOG.md b/CHANGELOG.md index 1901a725..5990b775 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [v3.2.1] - 2024-11-14 ### Added +- Added `dockerfiles/Dockerfile.ci.os` and `dockerfiles/Dockerfile.ci.es`, along with their respective entrypoints [#311](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/311) -- Added Docker image publishing to GitHub Container Registry in publish.yml [#311](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/311) +### Changed +- Updated the `publish.yml` workflow to include Docker image publishing to GitHub Container Registry [#311](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/311) +- Improved the README with detailed descriptions of the new Docker images, providing guidance for images. [#311](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/311) ## [v3.2.0] - 2024-10-09 diff --git a/README.md b/README.md index 6ec94b72..74d37e40 100644 --- a/README.md +++ b/README.md @@ -33,38 +33,98 @@ - We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md) -### To install from PyPI: +### Installing STAC-FastAPI from PyPI -```shell +To install STAC-FastAPI with Elasticsearch or OpenSearch backend support, run the following command: + +For Elasticsearch: +```bash pip install stac_fastapi.elasticsearch ``` -or -``` + +For OpenSearch: +```bash pip install stac_fastapi.opensearch ``` -## Build Elasticsearch API backend +## Running STAC-FastAPI Elasticsearch or OpenSearch API on `localhost:8080` -```shell -docker-compose up elasticsearch -docker-compose build app-elasticsearch +Before starting, [Docker](https://docs.docker.com/get-started/) or [Podman](https://podman.io/docs) has to be installed and running on your machine. + +### Step 1: Configure the `.env` File + +You need to provide a `.env` file to configure the environment variables. Here's a list of variables you can configure: + +- `STAC_FASTAPI_TITLE`: Title of the API shown in the documentation (default: `stac-fastapi-elasticsearch` or `stac-fastapi-opensearch`) +- `STAC_FASTAPI_DESCRIPTION`: Description of the API in the documentation +- `STAC_FASTAPI_VERSION`: API version (default: `2.1`) +- `APP_HOST`: Host to bind the server (default: `0.0.0.0`) +- `APP_PORT`: Port to bind the server (default: `8080`) +- `RELOAD`: Enable auto-reload for development (default: `true`) +- `ENVIRONMENT`: Runtime environment (default: `local`) +- `WEB_CONCURRENCY`: Number of worker processes (default: `10`) +- `ES_HOST`: Elasticsearch or OpenSearch host (default: `localhost`) +- `ES_PORT`: Elasticsearch port (default: `9200` for Elasticsearch, `9202` for OpenSearch) +- `ES_USE_SSL`: Enable SSL for Elasticsearch (default: `false`) +- `ES_VERIFY_CERTS`: Verify SSL certificates (default: `false`) +- `BACKEND`: Backend type (`elasticsearch` or `opensearch`) +- `STAC_FASTAPI_RATE_LIMIT`: API rate limit per client (default: `200/minute`) + +> [!NOTE] +> The variables `ES_HOST`, `ES_PORT`, `ES_USE_SSL`, and `ES_VERIFY_CERTS` apply to both Elasticsearch and OpenSearch, so there is no need to rename the key names to `OS_` even if you're using OpenSearch. + +### Step 2: Running the Backend with Elasticsearch + +To run the backend with Elasticsearch, use the following command: + +```bash +docker run -d \ + --env-file .env \ + -p 9200:9200 \ + -p 8080:8080 \ + ghcr.io/stac-utils/stac-fastapi-es:latest +``` +or +```bash +podman run -d \ + --env-file .env \ + -p 9200:9200 \ + -p 8080:8080 \ + ghcr.io/stac-utils/stac-fastapi-es:latest ``` -## Running Elasticsearch API on localhost:8080 +### Step 3: Running the Backend with OpenSearch -```shell -docker-compose up app-elasticsearch +To run the backend with OpenSearch, use the following command: + +```bash +docker run -d \ + --env-file .env \ + -p 9202:9202 \ + -p 8080:8080 \ + ghcr.io/stac-utils/stac-fastapi-os:latest ``` +or +```bash +podman run -d \ + --env-file .env \ + -p 9202:9202 \ + -p 8080:8080 \ + ghcr.io/stac-utils/stac-fastapi-os:latest +``` +### Step 4: Verifying the Backend is Running -By default, docker-compose uses Elasticsearch 8.x and OpenSearch 2.11.1. -If you wish to use a different version, put the following in a -file named `.env` in the same directory you run docker-compose from: +To check if the container is running, use the following command depending on whether you're using Docker or Podman: -```shell -ELASTICSEARCH_VERSION=7.17.1 -OPENSEARCH_VERSION=2.11.0 +```bash +docker ps ``` -The most recent Elasticsearch 7.x versions should also work. See the [opensearch-py docs](https://github.com/opensearch-project/opensearch-py/blob/main/COMPATIBILITY.md) for compatibility information. +or +```bash +podman ps +``` + +## Interacting with the API To create a new Collection: