Skip to content

Commit ca39061

Browse files
pantierrapantierra
committed
Included eoapi-k8s docs in mkdocs build for eoapi.dev
1 parent 025da1b commit ca39061

File tree

6 files changed

+213
-151
lines changed

6 files changed

+213
-151
lines changed

‎.github/workflows/deploy_mkdocs.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ on:
1111
- 'CONTRIBUTING.md'
1212
- 'docs/**'
1313
- '.github/workflows/deploy_mkdocs.yml'
14+
workflow_dispatch: # Allow manual triggering
15+
schedule:
16+
# Run daily at 6 AM UTC to check for updates in eoapi-k8s docs
17+
- cron: '0 6 * * *'
1418

1519
jobs:
1620
build:
@@ -20,6 +24,51 @@ jobs:
2024
- name: Checkout main
2125
uses: actions/checkout@v3
2226

27+
- name: Checkout eoapi-k8s docs
28+
uses: actions/checkout@v3
29+
with:
30+
repository: developmentseed/eoapi-k8s
31+
path: eoapi-k8s-temp
32+
ref: main
33+
34+
- name: Setup Kubernetes docs directory
35+
run: |
36+
mkdir -p docs/src/deployment/kubernetes
37+
38+
if [ -f "eoapi-k8s-temp/docs/docs-config.json" ]; then
39+
echo "Using docs-config.json for structured documentation sync"
40+
41+
find eoapi-k8s-temp/docs -name "*.md" -not -name "README.md" \
42+
-exec cp {} docs/src/deployment/kubernetes/ \;
43+
44+
ASSETS_DIR=$(grep -o '"assets_dir": *"[^"]*"' eoapi-k8s-temp/docs/docs-config.json | cut -d'"' -f4)
45+
if [ -n "$ASSETS_DIR" ] && [ -d "eoapi-k8s-temp/docs/$ASSETS_DIR" ]; then
46+
cp -r "eoapi-k8s-temp/docs/$ASSETS_DIR" docs/src/deployment/kubernetes/
47+
fi
48+
49+
find eoapi-k8s-temp/docs -name "*.svg" \
50+
-exec cp {} docs/src/deployment/kubernetes/ \;
51+
else
52+
echo "Fallback: copying all documentation files"
53+
54+
find eoapi-k8s-temp/docs -name "*.md" \
55+
-exec cp {} docs/src/deployment/kubernetes/ \;
56+
if [ -d "eoapi-k8s-temp/docs/images" ]; then
57+
cp -r eoapi-k8s-temp/docs/images docs/src/deployment/kubernetes/
58+
fi
59+
find eoapi-k8s-temp/docs -name "*.svg" \
60+
-exec cp {} docs/src/deployment/kubernetes/ \;
61+
fi
62+
63+
cat >> docs/src/deployment/kubernetes/index.md << EOF
64+
65+
---
66+
67+
*Documentation last synchronized: $(date -u +"%Y-%m-%d %H:%M:%S UTC")*
68+
EOF
69+
70+
rm -rf eoapi-k8s-temp
71+
2372
- name: Set up Python 3.8
2473
uses: actions/setup-python@v4
2574
with:

‎.gitignore‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,10 @@ node_modules/
114114
# Demo files to ignore
115115
demo/cmip6/CMIP6_daily_*stac_items.ndjson
116116

117-
118117
# browser compiled code and default config
119118
infrastructure/aws/stac-browser
120-
infrastructure/aws/browser_config.js
119+
infrastructure/aws/browser_config.js
120+
121+
# imported docs
122+
docs/src/deployment/kubernetes/
123+
eoapi-k8s/

‎Makefile‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
.PHONY: docs-sync docs-build docs-serve docs-clean help
2+
3+
# Default target
4+
help:
5+
@echo "Available commands:"
6+
@echo " docs-sync - Sync eoapi-k8s documentation"
7+
@echo " docs-build - Build documentation site"
8+
@echo " docs-serve - Serve documentation locally"
9+
@echo " docs-clean - Clean documentation build files"
10+
11+
# Sync eoapi-k8s documentation
12+
docs-sync:
13+
@echo "Syncing eoapi-k8s documentation..."
14+
@mkdir -p docs/src/deployment/kubernetes
15+
@if [ ! -d "eoapi-k8s" ]; then \
16+
git clone https://github.com/developmentseed/eoapi-k8s.git; \
17+
fi
18+
@cd eoapi-k8s && git fetch && git checkout main
19+
@if [ -f "eoapi-k8s/docs/docs-config.json" ]; then \
20+
find eoapi-k8s/docs -name "*.md" -not -name "README.md" -exec cp {} docs/src/deployment/kubernetes/ \;; \
21+
ASSETS_DIR=$$(grep -o '"assets_dir": *"[^"]*"' eoapi-k8s/docs/docs-config.json | cut -d'"' -f4); \
22+
if [ -n "$$ASSETS_DIR" ] && [ -d "eoapi-k8s/docs/$$ASSETS_DIR" ]; then \
23+
cp -r "eoapi-k8s/docs/$$ASSETS_DIR" docs/src/deployment/kubernetes/; \
24+
fi; \
25+
find eoapi-k8s/docs -name "*.svg" -exec cp {} docs/src/deployment/kubernetes/ \;; \
26+
fi
27+
@echo "" >> docs/src/deployment/kubernetes/index.md
28+
@echo "---" >> docs/src/deployment/kubernetes/index.md
29+
@echo "" >> docs/src/deployment/kubernetes/index.md
30+
@echo "*Documentation last synchronized: $$(date -u +"%Y-%m-%d %H:%M:%S UTC")*" >> docs/src/deployment/kubernetes/index.md
31+
@echo "Documentation sync complete!"
32+
33+
# Build documentation
34+
docs-build: docs-sync
35+
@cd docs && mkdocs build
36+
37+
# Serve documentation locally
38+
docs-serve: docs-sync
39+
@cd docs && mkdocs serve
40+
41+
# Clean documentation build files
42+
docs-clean:
43+
@rm -rf docs/build docs/src/deployment/kubernetes eoapi-k8s
44+
@echo "Documentation cleaned!"

‎docs/mkdocs.yml‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,23 @@ nav:
2929
- Contributing: contributing.md
3030
- Advanced User Guide:
3131
- Customization: customization.md
32-
- Deployment: deployment.md
32+
- Deployment:
33+
- deployment.md
34+
- Kubernetes:
35+
- Overview: deployment/kubernetes/index.md
36+
- Installation:
37+
- Quick Start: deployment/kubernetes/quick-start.md
38+
- Helm Install: deployment/kubernetes/helm-install.md
39+
- Configuration: deployment/kubernetes/configuration.md
40+
- Operations:
41+
- Manage Data: deployment/kubernetes/manage-data.md
42+
- Autoscaling: deployment/kubernetes/autoscaling.md
43+
- Unified Ingress: deployment/kubernetes/unified-ingress.md
44+
- STAC Auth Proxy: deployment/kubernetes/stac-auth-proxy.md
45+
- Release: deployment/kubernetes/release.md
46+
- AWS CDK:
47+
- Overview: deployment/aws/index.md
48+
3349

3450
plugins:
3551
- search

‎docs/src/deployment.md‎

Lines changed: 14 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,157 +1,23 @@
1-
---
2-
hide:
3-
- navigation
4-
---
1+
# Deployment
52

3+
eoAPI can be deployed using Kubernetes or AWS CDK.
64

7-
## Via [eoapi-cdk](https://github.com/developmentseed/eoapi-cdk)
5+
## Kubernetes (Recommended)
86

7+
Production-ready deployment with high availability, auto-scaling, and monitoring.
98

10-
[eoapi-cdk](https://github.com/developmentseed/eoapi-cdk) is a set of AWS CDK constructs that can be used to easily deploy eoAPI services on AWS with the CDK.
9+
**→ [Complete Kubernetes Documentation](./deployment/kubernetes/index.md)**
1110

12-
[eoapi-template](https://github.com/developmentseed/eoapi-template) is an AWS CDK app that shows how to configure the [eoapi-cdk](https://github.com/developmentseed/eoapi-cdk) constructs.
11+
- Multi-cloud support (AWS, GCP, Azure)
12+
- Helm-based installation
13+
- Built-in monitoring and autoscaling
1314

14-
An example of Cloud Stack is available for AWS (RDS for the database and Lambda for the APIs).
15+
## AWS CDK
1516

16-
The stack is deployed by the [AWS CDK](https://aws.amazon.com/cdk/) utility. Under the hood, CDK will create the deployment packages required for AWS Lambda, upload them to AWS, and handle the creation of the Lambda and API Gateway resources.
17+
Serverless deployment using AWS Lambda, RDS, and API Gateway.
1718

18-
The example commands here will deploy a CloudFormation stack called `eoAPI-staging`.
19+
**→ [Complete AWS CDK Documentation](./deployment/aws/index.md)**
1920

20-
1. Clone the `eoapi` repo and install dependencies
21-
```bash
22-
# Download eoapi repo
23-
git clone https://github.com/developmentseed/eoapi-template.git
24-
cd eoapi-template
25-
26-
# Create a virtual environment
27-
python -m venv .venv
28-
source .venv/bin/activate
29-
30-
# install cdk dependencies
31-
python -m pip install -r requirements.txt
32-
```
33-
34-
2. Install node dependency - requires node version 14+
35-
```bash
36-
npm install
37-
```
38-
39-
3. Update settings
40-
41-
Set environment variable or complex code in the `.env` or `config.yaml` file (e.g., https://github.com/developmentseed/eoapi-template/blob/main/config.yaml.example).
42-
43-
See https://github.com/developmentseed/eoapi-template/blob/main/infrastructure/config.py for more info on the configuration options.
44-
45-
46-
4. Install CDK and connect to your AWS account. This step is only necessary once per AWS account. The environment variables `PROJECT_ID` and `STAGE` determines the name of the stack
47-
(e.g., eoAPI-staging or eoAPI-production)
48-
```bash
49-
# Deploy the CDK toolkit stack into an AWS environment.
50-
PROJECT_ID=eoAPI \
51-
STAGE=staging \
52-
npx cdk bootstrap
53-
54-
# or to a specific region
55-
AWS_DEFAULT_REGION=us-west-2 \
56-
AWS_REGION=us-west-2 \
57-
PROJECT_ID=eoAPI \
58-
STAGE=staging \
59-
npx cdk bootstrap
60-
```
61-
62-
5. Pre-Generate CFN template
63-
64-
```bash
65-
PROJECT_ID=eoAPI \
66-
STAGE=staging \
67-
npx cdk synth --all # Synthesizes and prints the CloudFormation template for this stack
68-
```
69-
70-
6. Deploy
71-
72-
```bash
73-
# Note: a VPC stack is needed for the database
74-
PROJECT_ID=eoAPI \
75-
STAGE=staging \
76-
npx cdk deploy vpceoAPI-staging eoAPI-staging
77-
78-
# Deploy in a specific region
79-
AWS_DEFAULT_REGION=eu-central-1 \
80-
AWS_REGION=eu-central-1 \
81-
PROJECT_ID=eoAPI \
82-
STAGE=staging \
83-
npx cdk deploy vpceoAPI-staging eoAPI-stagingg --profile {my-aws-profile}
84-
```
85-
86-
If you get an error saying that the max VPCs have been reached, you have hit the limit for the number of VPCs per unique AWS account and region combination. You can change the AWS region to a region with fewer VPCs and deploy again to fix this.
87-
88-
## Via [eoapi-k8s](https://github.com/developmentseed/eoapi-k8s)
89-
90-
[eoapi-k8s](https://github.com/developmentseed/eoapi-k8s) has the IaC and Helm charts for deploying eoAPI services on AWS and GCP.
91-
92-
**Getting started**
93-
94-
If you still need to set up a k8s cluster on AWS or GCP, then follow an IaC guide below that is relevant to you.
95-
96-
> &#9432; The helm chart in this repo assumes your cluster has a few third-party add-ons and controllers installed. So
97-
> It's in your best interest to read through the IaC guides to understand what those defaults are
98-
99-
* :octicons-link-external-16: [AWS EKS Cluster Setup](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/aws-eks.md)
100-
101-
* :octicons-link-external-16: [TBD: GCP GKE Cluster Setup](https://github.com/developmentseed/eoapi-k8s/blob/main/docs/gcp-gke.md)
102-
103-
**Helm Installation**
104-
105-
Once you have a k8s cluster set up, you can `helm install` eoAPI as follows
106-
107-
1. `helm install` from this repo's `helm-chart/` folder:
108-
109-
```python
110-
######################################################
111-
# create os environment variables for required secrets
112-
######################################################
113-
$ export GITSHA=$(git rev-parse HEAD | cut -c1-10)
114-
$ export PGUSER=s00pers3cr3t
115-
$ export POSTGRES_USER=s00pers3cr3t
116-
$ export POSTGRES_PASSWORD=superuserfoobar
117-
$ export PGPASSWORD=foobar
118-
119-
$ cd ./helm-chart
120-
121-
$ helm install \
122-
--namespace eoapi \
123-
--create-namespace \
124-
--set gitSha=$GITSHA \
125-
--set db.settings.secrets.PGUSER=$PGUSER \
126-
--set db.settings.secrets.POSTGRES_USER=$POSTGRES_USER \
127-
--set db.settings.secrets.PGPASSWORD=$PGPASSWORD \
128-
--set db.settings.secrets.POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
129-
eoapi \
130-
./eoapi
131-
```
132-
133-
2. or `helm install` from https://devseed.com/eoapi-k8s/:
134-
135-
```python
136-
# add the eoapi helm repo locally
137-
$ helm repo add eoapi https://devseed.com/eoapi-k8s/
138-
139-
# List out the eoapi chart versions
140-
$ helm search repo eoapi
141-
NAME CHART VERSION APP VERSION DESCRIPTION
142-
eoapi/eoapi 0.1.1 0.1.0 Create a full Earth Observation API with Metada...
143-
eoapi/eoapi 0.1.2 0.1.0 Create a full Earth Observation API with Metada...
144-
145-
# add the required secret overrides to an arbitrarily named `.yaml` file (`config.yaml` below)
146-
$ cat config.yaml
147-
db:
148-
settings:
149-
secrets:
150-
PGUSER: "username"
151-
POSTGRES_USER: "username"
152-
PGPASSWORD: "password"
153-
POSTGRES_PASSWORD: "password"
154-
155-
# then run `helm install` with those overrides
156-
helm install eoapi eoapi/eoapi --version 0.1.1 -f config.yaml
157-
```
21+
- Pay-per-request pricing
22+
- Managed infrastructure
23+
- AWS-native integration

0 commit comments

Comments
 (0)