Skip to content

Commit c97d6f0

Browse files
mo-dkrzmo-dkrz
committed
add RUN_LOCAL_OS and RUN_LOCAL_ES option to configure backend in container and updated readme
1 parent bd5cddf commit c97d6f0

File tree

5 files changed

+117
-71
lines changed

5 files changed

+117
-71
lines changed

‎README.md‎

Lines changed: 82 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -47,71 +47,104 @@ For OpenSearch:
4747
pip install stac_fastapi.opensearch
4848
```
4949

50-
## Running STAC-FastAPI Elasticsearch or OpenSearch API on `localhost:8080`
50+
## Running STAC-FastAPI Elasticsearch or OpenSearch API
5151

5252
Before starting, [Docker](https://docs.docker.com/get-started/) or [Podman](https://podman.io/docs) has to be installed and running on your machine.
5353

54-
### Step 1: Configure the `.env` File (Optional)
54+
### Step 1: Configure the `.env` File
5555

56-
If you need to modify the default configuration, provide a `.env` file with your environment variables. Here's a list of configurable variables. If you're comfortable with the defaults, you can run the Docker container without any environment configuration.
56+
The `.env` file lets you customize the runtime configuration. If you plan to connect to an external Elasticsearch or OpenSearch instance, set the `ES_HOST` and `ES_PORT` variables to point to your external server.
5757

58-
- `STAC_FASTAPI_TITLE`: Title of the API shown in the documentation (default: `stac-fastapi-elasticsearch` or `stac-fastapi-opensearch`)
59-
- `STAC_FASTAPI_DESCRIPTION`: Description of the API in the documentation
60-
- `STAC_FASTAPI_VERSION`: API version (default: `2.1`)
61-
- `APP_HOST`: Host to bind the server (default: `0.0.0.0`)
62-
- `APP_PORT`: Port to bind the server (default: `8080`)
63-
- `ENVIRONMENT`: Runtime environment (default: `local`)
64-
- `WEB_CONCURRENCY`: Number of worker processes if more workers are needed (default: `10`)
65-
- `RELOAD`: Enable auto-reload for development (default: `true`)
66-
- `ES_HOST`: Elasticsearch or OpenSearch host (default: `localhost`)
67-
- `ES_PORT`: Elasticsearch port (default: `9200` for Elasticsearch, `9202` for OpenSearch)
68-
- `ES_USE_SSL`: Enable SSL for Elasticsearch (default: `false`)
69-
- `ES_VERIFY_CERTS`: Verify SSL certificates (default: `false`)
70-
- `STAC_FASTAPI_RATE_LIMIT`: API rate limit per client (default: `200/minute`)
58+
Alternatively, if you want to run Elasticsearch or OpenSearch **within the same container** as the STAC-FastAPI, enable the respective environment variable in the `.env` file:
7159

72-
> [!NOTE]
73-
> 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.
60+
- **`RUN_LOCAL_ES`**: Set to `1` to run Elasticsearch locally within the container (default: `0`). Use this with the `stac-fastapi-es` image.
61+
- **`RUN_LOCAL_OS`**: Set to `1` to run OpenSearch locally within the container (default: `0`). Use this with the `stac-fastapi-os` image.
7462

75-
### Step 2.1: Running the Backend with Elasticsearch
63+
> [!IMPORTANT]
64+
> The variables `RUN_LOCAL_ES` and `RUN_LOCAL_OS` correspond to **different Docker images**:
65+
> - Use `RUN_LOCAL_ES` with the `ghcr.io/stac-utils/stac-fastapi-es` image.
66+
> - Use `RUN_LOCAL_OS` with the `ghcr.io/stac-utils/stac-fastapi-os` image.
7667
77-
To run the backend with Elasticsearch, use the following command:
7868

79-
```bash
80-
docker run -d \
81-
-p 9200:9200 \
82-
-p 8080:8080 \
83-
ghcr.io/stac-utils/stac-fastapi-es:latest
84-
```
85-
or
86-
```bash
87-
podman run -d \
88-
-p 9200:9200 \
89-
-p 8080:8080 \
90-
ghcr.io/stac-utils/stac-fastapi-es:latest
91-
```
69+
Here are the key variables to configure:
9270

93-
### Step 2.2: Running the Backend with OpenSearch
71+
| Variable | Description | Default | Required |
72+
|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
73+
| `RUN_LOCAL_ES` | Enable local Elasticsearch in the container. | `0` | Optional (set to `1` to run local Elasticsearch) |
74+
| `RUN_LOCAL_OS` | Enable local OpenSearch in the container. | `0` | Optional (set to `1` to run local OpenSearch) |
75+
| `ES_HOST` | Hostname for external Elasticsearch/OpenSearch. | `localhost` | **Required if `RUN_LOCAL_ES=0` or `RUN_LOCAL_OS=0`** |
76+
| `ES_PORT` | Port for Elasticsearch/OpenSearch. | `9200` (ES) / `9202` (OS)| **Required if `RUN_LOCAL_ES=0` or `RUN_LOCAL_OS=0`** |
77+
| `ES_USE_SSL` | Use SSL for connecting to Elasticsearch/OpenSearch. | `false` | Optional |
78+
| `ES_VERIFY_CERTS` | Verify SSL certificates when connecting. | `false` | Optional |
79+
| `STAC_FASTAPI_TITLE` | Title of the API in the documentation. | `stac-fastapi-elasticsearch` or `stac-fastapi-opensearch` | Optional |
80+
| `STAC_FASTAPI_DESCRIPTION` | Description of the API in the documentation. | N/A | Optional |
81+
| `STAC_FASTAPI_VERSION` | API version. | `2.1` | Optional |
82+
| `APP_HOST` | Server bind address. | `0.0.0.0` | Optional |
83+
| `APP_PORT` | Server port. | `8080` | Optional |
84+
| `ENVIRONMENT` | Runtime environment. | `local` | Optional |
85+
| `WEB_CONCURRENCY` | Number of worker processes. | `10` | Optional |
86+
| `RELOAD` | Enable auto-reload for development. | `true` | Optional |
87+
| `STAC_FASTAPI_RATE_LIMIT` | API rate limit per client. | `200/minute` | Optional |
9488

95-
To run the backend with OpenSearch, use the following command:
9689

97-
```bash
98-
docker run -d \
99-
-p 9202:9202 \
100-
-p 8080:8080 \
101-
ghcr.io/stac-utils/stac-fastapi-os:latest
102-
```
103-
or
104-
```bash
105-
podman run -d \
106-
-p 9202:9202 \
107-
-p 8080:8080 \
108-
ghcr.io/stac-utils/stac-fastapi-os:latest
109-
```
90+
> [!NOTE]
91+
> 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.
92+
93+
94+
### Step 2: Running the Backend
95+
96+
Depending on your setup, follow one of the options below:
97+
98+
#### **Option A: Connect to External Elasticsearch/OpenSearch**
99+
100+
1. Update the `.env` file to include the `ES_HOST` and `ES_PORT` values of your external ES/OS instance. (Based on the SSL certification you might need to consider changing `ES_USE_SSL` and `ES_VERIFY_CERTS`)
101+
2. Run the container with the appropriate image:
102+
- For Elasticsearch:
103+
```bash
104+
docker run -d \
105+
-p 8080:8080 \
106+
--env-file .env \
107+
ghcr.io/stac-utils/stac-fastapi-es:latest
108+
```
109+
- For OpenSearch:
110+
```bash
111+
docker run -d \
112+
-p 8080:8080 \
113+
--env-file .env \
114+
ghcr.io/stac-utils/stac-fastapi-os:latest
115+
```
116+
117+
#### **Option B: Run Elasticsearch/OpenSearch Locally in the Same Container**
118+
119+
If you'd like to run Elasticsearch or OpenSearch in the same container as the API:
120+
121+
1. In the `.env` file, enable the variable corresponding to your backend choice:
122+
- Set `RUN_LOCAL_ES=1` to use Elasticsearch.
123+
- Set `RUN_LOCAL_OS=1` to use OpenSearch.
124+
125+
2. Start the container using the appropriate image:
126+
127+
- For **Elasticsearch**:
128+
```bash
129+
docker run -d \
130+
-p 9200:9200 \
131+
-p 8080:8080 \
132+
-e RUN_LOCAL_ES=1 \
133+
ghcr.io/stac-utils/stac-fastapi-es:latest
134+
```
135+
- For **OpenSearch**:
136+
```bash
137+
docker run -d \
138+
-p 9202:9202 \
139+
-p 8080:8080 \
140+
-e RUN_LOCAL_OS=1 \
141+
ghcr.io/stac-utils/stac-fastapi-os:latest
142+
```
110143
111144
> [!TIP]
112145
> If you need to mount a volume, use the [`-v`](https://docs.docker.com/engine/storage/volumes/#choose-the--v-or---mount-flag) flag. To specify an environment file, use the [`--env-file`](https://docs.docker.com/reference/cli/docker/container/run/#env) flag.
113146
114-
### Step 3: Verifying the Backend is Running
147+
### Step 3: Verifying the STAC-FastAPI ELasticSearch or OpenSearch is Running
115148
116149
To check if the container is running, use the following command depending on whether you're using Docker or Podman:
117150

‎dockerfiles/Dockerfile.ci.es‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ENV WEB_CONCURRENCY=10
55
ENV ES_USE_SSL=false
66
ENV ES_VERIFY_CERTS=false
77
ENV STAC_FASTAPI_RATE_LIMIT="200/minute"
8+
ENV RUN_LOCAL_ES=0
89

910
RUN apt-get update && \
1011
apt-get install -y --no-install-recommends \
@@ -44,10 +45,9 @@ ENV ES_JAVA_OPTS="-Xms512m -Xmx1g" \
4445

4546

4647
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 CMD \
47-
curl --silent --fail http://${ES_HOST}:${ES_PORT}/_cluster/health || exit 1 && \
4848
curl --silent --fail http://${APP_HOST}:${APP_PORT}/api.html || exit 1
4949

50-
EXPOSE $APP_PORT $ES_PORT
50+
EXPOSE $APP_PORT
5151

5252
USER elasticsearch
5353
ENTRYPOINT ["/entrypoint.sh"]

‎dockerfiles/Dockerfile.ci.os‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ ENV WEB_CONCURRENCY=10
55
ENV ES_USE_SSL=false
66
ENV ES_VERIFY_CERTS=false
77
ENV STAC_FASTAPI_RATE_LIMIT="200/minute"
8+
ENV RUN_LOCAL_OS=0
89

910
RUN apt-get update && \
1011
apt-get install -y --no-install-recommends \
@@ -42,10 +43,9 @@ ENV OPENSEARCH_JAVA_OPTS="-Xms512m -Xmx1g" \
4243
PATH="/usr/share/opensearch/bin:${PATH}"
4344

4445
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 CMD \
45-
curl --silent --fail http://${ES_HOST}:${ES_PORT}/_cluster/health || exit 1 && \
4646
curl --silent --fail http://${APP_HOST}:${APP_PORT}/api.html || exit 1
4747

48-
EXPOSE $APP_PORT $ES_PORT
48+
EXPOSE $APP_PORT
4949

5050
USER opensearch
5151
ENTRYPOINT ["/entrypoint.sh"]

‎dockerfiles/entrypoint-es.sh‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
#!/bin/bash
2-
export WEB_CONCURRENCY="${WEB_CONCURRENCY:-10}"
32
function validate_elasticsearch {
43
health=$(curl -s -o /dev/null -w '%{http_code}' "http://${ES_HOST}:${ES_PORT}/_cluster/health")
54
if [ "$health" -eq 200 ]; then
@@ -9,15 +8,21 @@ function validate_elasticsearch {
98
fi
109
}
1110

12-
echo "start es"
13-
/usr/share/elasticsearch/bin/elasticsearch &
11+
if [ "${RUN_LOCAL_ES}" = "1" ]; then
12+
echo "starting elasticsearch"
13+
/usr/share/elasticsearch/bin/elasticsearch &
1414

15-
echo "wait for es to be ready"
16-
until validate_elasticsearch; do
17-
echo -n "."
18-
sleep 5
19-
done
20-
echo "Elasticsearch is up"
15+
echo "wait for es to be ready"
16+
until validate_elasticsearch; do
17+
echo -n "."
18+
sleep 5
19+
done
20+
echo "Elasticsearch is up"
21+
fi
2122

2223
echo "start stac-fastapi-es"
23-
exec uvicorn stac_fastapi.elasticsearch.app:app --host "${APP_HOST}" --port "${APP_PORT}" --reload
24+
exec uvicorn stac_fastapi.elasticsearch.app:app \
25+
--host "${APP_HOST}" \
26+
--port "${APP_PORT}" \
27+
--workers "${WEB_CONCURRENCY}" \
28+
--reload

‎dockerfiles/entrypoint-os.sh‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
#!/bin/bash
2-
export WEB_CONCURRENCY="${WEB_CONCURRENCY:-10}"
32
function validate_opensearch {
43
health=$(curl -s -o /dev/null -w '%{http_code}' "http://${ES_HOST}:${ES_PORT}/_cluster/health")
54
if [ "$health" -eq 200 ]; then
@@ -12,12 +11,21 @@ function validate_opensearch {
1211
echo "start opensearch"
1312
/usr/share/opensearch/bin/opensearch &
1413

15-
echo "wait for opensearch to be ready"
16-
until validate_opensearch; do
17-
echo -n "."
18-
sleep 5
19-
done
20-
echo "opensearch is up."
14+
if [ "${RUN_LOCAL_OS}" = "1" ]; then
15+
echo "starting opensearch"
16+
/usr/share/opensearch/bin/opensearch &
17+
18+
echo "wait for os to be ready"
19+
until validate_opensearch; do
20+
echo -n "."
21+
sleep 5
22+
done
23+
echo "opensearch is up"
24+
fi
2125

2226
echo "start stac-fastapi-os"
23-
exec uvicorn stac_fastapi.opensearch.app:app --host "${APP_HOST}" --port "${APP_PORT}" --reload
27+
exec uvicorn stac_fastapi.opensearch.app:app \
28+
--host "${APP_HOST}" \
29+
--port "${APP_PORT}" \
30+
--workers "${WEB_CONCURRENCY}" \
31+
--reload

0 commit comments

Comments
 (0)