Skip to content

Commit 7226fc1

Browse files
mo-dkrzmo-dkrz
committed
better docs
1 parent c97d6f0 commit 7226fc1

File tree

6 files changed

+105
-72
lines changed

6 files changed

+105
-72
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ jobs:
107107
- name: Test Elasticsearch image
108108
run: |
109109
docker run -d --name stac-es \
110+
-e RUN_LOCAL_ES=1 \
110111
stac-fastapi-es:test
111112
112113
timeout=120
@@ -165,6 +166,7 @@ jobs:
165166
- name: Test OpenSearch image
166167
run: |
167168
docker run -d --name stac-os \
169+
-e RUN_LOCAL_OS=1 \
168170
stac-fastapi-os:test
169171
170172
timeout=120

‎README.md‎

Lines changed: 95 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -49,24 +49,112 @@ pip install stac_fastapi.opensearch
4949

5050
## Running STAC-FastAPI Elasticsearch or OpenSearch API
5151

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

54-
### Step 1: Configure the `.env` File
54+
- [**Docker**](https://docs.docker.com/get-started/) or [**Podman**](https://podman.io/docs) installed and running on your machine.
5555

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.
56+
### Step 1: Set Up the Environment Variables
57+
Create a `.env` file to configure your setup. Depending on your preference, you can either connect to an external Elasticsearch/OpenSearch instance or run one locally within the same container.
5758

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:
59+
#### Option A: Connect to an External Elasticsearch/OpenSearch Instance
5960

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.
61+
1. Open your `.env` file.
62+
2. Set the following variables to point to your external Elasticsearch or OpenSearch server:
63+
64+
```env
65+
ES_HOST=your_external_host
66+
ES_PORT=your_external_port
67+
ES_USE_SSL=false # Set to 'true' if your server uses SSL
68+
ES_VERIFY_CERTS=false # Set to 'true' to verify SSL certificates
69+
```
70+
71+
#### Option B: Run Elasticsearch/OpenSearch Locally
72+
73+
1. Open your `.env` file.
74+
2. Enable one of the following to run the service locally within the container:
75+
76+
```env
77+
# For Elasticsearch
78+
RUN_LOCAL_ES=1
79+
80+
# For OpenSearch
81+
RUN_LOCAL_OS=1
82+
```
6283

6384
> [!IMPORTANT]
6485
> The variables `RUN_LOCAL_ES` and `RUN_LOCAL_OS` correspond to **different Docker images**:
6586
> - Use `RUN_LOCAL_ES` with the `ghcr.io/stac-utils/stac-fastapi-es` image.
6687
> - Use `RUN_LOCAL_OS` with the `ghcr.io/stac-utils/stac-fastapi-os` image.
6788
89+
### Step 2: Run the STAC-FastAPI Container
90+
91+
#### Option A: Using an External Instance
92+
93+
- **For Elasticsearch:**
94+
95+
```bash
96+
docker run -d \
97+
-p 8080:8080 \
98+
--env-file .env \
99+
ghcr.io/stac-utils/stac-fastapi-es:latest
100+
```
101+
102+
- **For OpenSearch:**
103+
104+
```bash
105+
docker run -d \
106+
-p 8080:8080 \
107+
--env-file .env \
108+
ghcr.io/stac-utils/stac-fastapi-os:latest
109+
```
110+
111+
#### Option B: Running Locally in the Same Container as APP
112+
113+
- **For Elasticsearch:**
114+
115+
```bash
116+
docker run -d \
117+
-p 8080:8080 \
118+
-p 9200:9200 \
119+
--env-file .env \
120+
ghcr.io/stac-utils/stac-fastapi-es:latest
121+
```
122+
123+
- **For OpenSearch:**
124+
125+
```bash
126+
docker run -d \
127+
-p 8080:8080 \
128+
-p 9202:9202 \
129+
--env-file .env \
130+
ghcr.io/stac-utils/stac-fastapi-os:latest
131+
```
132+
133+
> [!TIP]
134+
> 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.
135+
136+
### Step 3: Verify the Service is Running
68137

69-
Here are the key variables to configure:
138+
Run the following command to check if your container is up and running:
139+
140+
```bash
141+
docker ps # "podman ps" if you are running via podman
142+
```
143+
144+
You should see the STAC-FastAPI container listed.
145+
146+
## Accessing the API
147+
148+
Once the container is up and running, access the API at:
149+
150+
```
151+
http://localhost:8080
152+
```
153+
154+
## Additional Configuration (Optional)
155+
156+
You can customize additional settings in your `.env` file:
157+
### Key variables to configure:
70158

71159
| Variable | Description | Default | Required |
72160
|------------------------------|--------------------------------------------------------------------------------------|--------------------------|---------------------------------------------------------------------------------------------|
@@ -91,71 +179,6 @@ Here are the key variables to configure:
91179
> 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.
92180
93181

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-
```
143-
144-
> [!TIP]
145-
> 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.
146-
147-
### Step 3: Verifying the STAC-FastAPI ELasticSearch or OpenSearch is Running
148-
149-
To check if the container is running, use the following command depending on whether you're using Docker or Podman:
150-
151-
```bash
152-
docker ps
153-
```
154-
or
155-
```bash
156-
podman ps
157-
```
158-
159182
## Interacting with the API
160183

161184
To create a new Collection:

‎dockerfiles/Dockerfile.ci.es‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
FROM debian:bookworm-slim AS base
22

33
ENV ENVIRONMENT="local"
4+
ENV APP_HOST="0.0.0.0"
5+
ENV APP_PORT="8080"
46
ENV WEB_CONCURRENCY=10
57
ENV ES_USE_SSL=false
68
ENV ES_VERIFY_CERTS=false

‎dockerfiles/Dockerfile.ci.os‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
FROM debian:bookworm-slim AS base
22

33
ENV ENVIRONMENT="local"
4+
ENV API_HOST="0.0.0.0"
5+
ENV API_PORT="8080"
46
ENV WEB_CONCURRENCY=10
57
ENV ES_USE_SSL=false
68
ENV ES_VERIFY_CERTS=false

‎dockerfiles/entrypoint-es.sh‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
#!/bin/bash
22
function validate_elasticsearch {
3+
export ES_HOST=${ES_HOST:-localhost}
4+
export ES_PORT=${ES_PORT:-9200}
35
health=$(curl -s -o /dev/null -w '%{http_code}' "http://${ES_HOST}:${ES_PORT}/_cluster/health")
46
if [ "$health" -eq 200 ]; then
57
return 0

‎dockerfiles/entrypoint-os.sh‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
#!/bin/bash
22
function validate_opensearch {
3+
export ES_HOST=${ES_HOST:-localhost}
4+
export ES_PORT=${ES_PORT:-9202}
35
health=$(curl -s -o /dev/null -w '%{http_code}' "http://${ES_HOST}:${ES_PORT}/_cluster/health")
46
if [ "$health" -eq 200 ]; then
57
return 0

0 commit comments

Comments
 (0)