You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+68-16Lines changed: 68 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,59 +6,111 @@ Template repository to deploy [eoapi](https://eoapi.dev) on AWS using the [eoapi
6
6
7
7
- python >=3.9
8
8
- docker
9
-
- node >=14
9
+
- node >=18
10
10
- AWS credentials environment variables configured to point to an account.
11
11
-**Optional** a `config.yaml` file to override the default deployment settings defined in `config.py`.
12
12
13
13
## Installation
14
14
15
-
Install python dependencies with
15
+
Install python dependencies with`uv`
16
16
17
-
```
18
-
python -m venv .venv
19
-
source .venv/bin/activate
20
-
python -m pip install -r requirements.txt
17
+
```bash
18
+
uv sync
21
19
```
22
20
23
21
And node dependencies with
24
22
25
-
```
23
+
```bash
26
24
npm install
27
25
```
28
26
29
27
Verify that the `cdk` CLI is available. Since `aws-cdk` is installed as a local dependency, you can use the `npx` node package runner tool, that comes with `npm`.
30
28
31
-
```
29
+
```bash
32
30
npx cdk --version
33
31
```
32
+
34
33
## Deployment
35
34
36
-
First, synthesize the app
35
+
### Configuration
36
+
37
+
You can configure your eoAPI deployment using either environment variables (defined manually or in a `.env` file) or a configuration yaml file (see [config.py](./infrastructure/config.py) for more details on all of the configurable parameters.
38
+
39
+
Feel free to add or subtract from these configuration parameters to suit your needs!
37
40
41
+
To start you can copy [config.yaml.example](./config.yaml.example) to config.yaml:
42
+
43
+
```bash
44
+
cp config.yaml.example config.yaml
38
45
```
39
-
npx cdk synth --all
46
+
47
+
Then update the values according to your preferences.
48
+
Be sure to set `project_id` to something recognizable and to look closely at all of the components that you are including with each setting.
49
+
50
+
### AWS credentials
51
+
52
+
For the deployment steps to work, you will need to have your environment configured with your AWS account credentials.
53
+
There are lots of ways to do this so choose whatever method you want to define `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, dtc.
54
+
55
+
### Synthesize the CDK Stack
56
+
57
+
You can test your deployment configuration without deploying any actual resources to AWS by using the `cdk synth` command.
58
+
59
+
```bash
60
+
uv run npx cdk synth --all
40
61
```
41
62
42
63
Then, deploy
43
64
65
+
```bash
66
+
uv run npx cdk deploy --all --require-approval never
44
67
```
45
-
npx cdk deploy --all --require-approval never
46
-
```
68
+
69
+
## GitHub Actions
70
+
71
+
The repository includes a CI workflow (`.github/workflows/ci.yml`) that runs on every push to `main` and on all pull requests. The workflow:
72
+
73
+
1. Sets up the build environment with Node.js 22 and Python (via `uv`)
74
+
2. Installs all project dependencies (both Python and Node)
75
+
3. Runs pre-commit hooks to check code quality and formatting
76
+
4. Synthesizes the CDK stack to validate the infrastructure-as-code configuration
77
+
78
+
This ensures that all code changes pass quality checks and that the CDK stack can be successfully synthesized before merging.
79
+
80
+
### Automated Deployment
81
+
82
+
The workflow also includes an example `deploy` job that demonstrates how to automatically deploy your eoAPI stack to AWS using GitHub Actions. This job showcases:
> This deployment job is a basic starting point and can be triggered manually via `workflow_dispatch`. You should tailor it to match your specific deployment strategy, such as:
> - Adding post-deployment validation or smoke tests
94
+
> - Customizing environment variables for different stages
95
+
> - Integrating with monitoring or notification systems
96
+
97
+
To set up AWS OIDC authentication for GitHub Actions, refer to the [AWS documentation on configuring OIDC with GitHub](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) and the [GitHub documentation for Configuring OpenID Connect in AWS](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws).
47
98
48
99
## Docker
49
100
50
101
Before deploying the application on the cloud, you can start by exploring it with a local *Docker* deployment
51
102
52
-
```
103
+
```bash
53
104
docker compose up
54
105
```
55
106
56
107
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)).
57
108
58
109
Then you can start exploring your dataset with:
59
110
60
-
- the STAC Metadata service [http://localhost:8081](http://localhost:8081)
61
-
- the Raster service [http://localhost:8082](http://localhost:8082)
62
-
- the browser UI [http://localhost:8085](http://localhost:8085)
111
+
- the STAC Metadata service [http://localhost:8081](http://localhost:8081)
112
+
- the Raster service [http://localhost:8082](http://localhost:8082)
113
+
- the Vector service [http://localhost:8083](http://localhost:8083)
114
+
- the browser UI [http://localhost:8085](http://localhost:8085)
63
115
64
116
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).
0 commit comments