swadhin / justapi public

p5d-i: add GKE, EKS, AKS, Fly.io, Railway deployment guides + Production Checklist

swadhinbiswas committed 3 months ago
f35b086
1 parent 18ed146
commit f35b086
6 files changed
+398 -0
Showing 6 changed files+398-0
docs_site/src/content/docs/deployment/aks.mddocs_site/src/content/docs/deployment/eks.mddocs_site/src/content/docs/deployment/flyio.mddocs_site/src/content/docs/deployment/gke.mddocs_site/src/content/docs/deployment/production-checklist.mddocs_site/src/content/docs/deployment/railway.md
▼docs_site/src/content/docs/deployment/aks.md
+62-0
@@ -0,0 +1,62 @@
1
+---
2
+title: Azure AKS
3
+description: Deploy JustAPI to Azure Kubernetes Service.
4
+---
5
+
6
+## 1. Create AKS Cluster
7
+
8
+```bash
9
+az group create --name justapi-rg --location eastus
10
+az aks create \
11
+ --resource-group justapi-rg \
12
+ --name justapi-cluster \
13
+ --node-count 3 \
14
+ --enable-managed-identity
15
+```
16
+
17
+## 2. Get Credentials
18
+
19
+```bash
20
+az aks get-credentials --resource-group justapi-rg --name justapi-cluster
21
+```
22
+
23
+## 3. Install NGINX Ingress Controller
24
+
25
+```bash
26
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml
27
+```
28
+
29
+## 4. Install cert-manager
30
+
31
+```bash
32
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
33
+```
34
+
35
+## 5. Build and Push to ACR
36
+
37
+```bash
38
+az acr create --resource-group justapi-rg --name justapiacr --sku Basic
39
+az acr build --registry justapiacr --image justapi-app:latest .
40
+```
41
+
42
+## 6. Attach ACR to AKS
43
+
44
+```bash
45
+az aks update --resource-group justapi-rg --name justapi-cluster --attach-acr justapiacr
46
+```
47
+
48
+## 7. Deploy with Helm
49
+
50
+```bash
51
+helm upgrade --install my-app justapi/justapi \
52
+ --set image.repository=justapiacr.azurecr.io/justapi-app \
53
+ --set image.tag=latest \
54
+ --set ingress.enabled=true \
55
+ --set ingress.host=api.example.com
56
+```
57
+
58
+## See Also
59
+
60
+- [Google Cloud (GKE)](/deployment/gke/) — Deploy on GCP
61
+- [Amazon EKS](/deployment/eks/) — Deploy on AWS
62
+- [Kubernetes / Helm](/deployment/kubernetes-helm/) — Helm chart reference
0
63
▼docs_site/src/content/docs/deployment/eks.md
+51-0
@@ -0,0 +1,51 @@
1
+---
2
+title: Amazon EKS
3
+description: Deploy JustAPI to Amazon Elastic Kubernetes Service.
4
+---
5
+
6
+## 1. Create EKS Cluster
7
+
8
+```bash
9
+eksctl create cluster \
10
+ --name justapi-cluster \
11
+ --region us-east-1 \
12
+ --nodegroup-name standard \
13
+ --node-type t3.medium \
14
+ --nodes 3
15
+```
16
+
17
+## 2. Configure kubectl
18
+
19
+```bash
20
+aws eks update-kubeconfig --region us-east-1 --name justapi-cluster
21
+```
22
+
23
+## 3. Install AWS Load Balancer Controller
24
+
25
+```bash
26
+kubectl apply -k "github.com/aws/load-balancer-controller//deploy/overlays/eks"
27
+```
28
+
29
+## 4. Build and Push to ECR
30
+
31
+```bash
32
+aws ecr create-repository --repository-name justapi-app
33
+docker build -t $ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/justapi-app:latest .
34
+docker push $ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/justapi-app:latest
35
+```
36
+
37
+## 5. Deploy with Helm (ALB Ingress)
38
+
39
+```bash
40
+helm upgrade --install my-app justapi/justapi \
41
+ --set image.repository=$ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/justapi-app \
42
+ --set image.tag=latest \
43
+ --set ingress.enabled=true \
44
+ --set ingress.className=alb
45
+```
46
+
47
+## See Also
48
+
49
+- [Google Cloud (GKE)](/deployment/gke/) — Deploy on GCP
50
+- [Azure AKS](/deployment/aks/) — Deploy on Azure
51
+- [Kubernetes / Helm](/deployment/kubernetes-helm/) — Helm chart reference
0
52
▼docs_site/src/content/docs/deployment/flyio.md
+62-0
@@ -0,0 +1,62 @@
1
+---
2
+title: Fly.io
3
+description: Deploy JustAPI to Fly.io for global edge deployment.
4
+---
5
+
6
+## 1. Install flyctl
7
+
8
+```bash
9
+curl -L https://fly.io/install.sh | sh
10
+```
11
+
12
+## 2. Create `fly.toml`
13
+
14
+```toml
15
+app = "my-justapi-app"
16
+primary_region = "iad"
17
+
18
+[build]
19
+ image = "my-justapi-app:latest"
20
+
21
+[http_service]
22
+ internal_port = 8080
23
+ force_https = true
24
+
25
+[[services]]
26
+ protocol = "tcp"
27
+ internal_port = 8080
28
+
29
+ [[services.ports]]
30
+ port = 80
31
+ handlers = ["http"]
32
+ [[services.ports]]
33
+ port = 443
34
+ handlers = ["tls", "http"]
35
+```
36
+
37
+## 3. Launch
38
+
39
+```bash
40
+flyctl launch
41
+flyctl deploy
42
+```
43
+
44
+## 4. Scale
45
+
46
+```bash
47
+flyctl scale count 3
48
+flyctl scale memory 512
49
+```
50
+
51
+## 5. Attach Database
52
+
53
+```bash
54
+flyctl postgres create
55
+flyctl postgres attach my-justapi-app
56
+```
57
+
58
+## See Also
59
+
60
+- [Railway](/deployment/railway/) — Deploy on Railway
61
+- [Docker](/deployment/docker/) — Container setup
62
+- [Production Checklist](/deployment/production-checklist/) — Production readiness
0
63
▼docs_site/src/content/docs/deployment/gke.md
+54-0
@@ -0,0 +1,54 @@
1
+---
2
+title: Google Cloud (GKE)
3
+description: Deploy JustAPI to Google Kubernetes Engine.
4
+---
5
+
6
+## 1. Create GKE Cluster
7
+
8
+```bash
9
+gcloud container clusters create justapi-cluster \
10
+ --zone us-central1-a \
11
+ --num-nodes 3 \
12
+ --machine-type e2-standard-2
13
+```
14
+
15
+## 2. Get Credentials
16
+
17
+```bash
18
+gcloud container clusters get-credentials justapi-cluster --zone us-central1-a
19
+```
20
+
21
+## 3. Install NGINX Ingress Controller
22
+
23
+```bash
24
+kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml
25
+```
26
+
27
+## 4. Install cert-manager
28
+
29
+```bash
30
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
31
+```
32
+
33
+## 5. Build and Push to GCR
34
+
35
+```bash
36
+docker build -t gcr.io/$PROJECT_ID/justapi-app:latest .
37
+docker push gcr.io/$PROJECT_ID/justapi-app:latest
38
+```
39
+
40
+## 6. Deploy with Helm
41
+
42
+```bash
43
+helm upgrade --install my-app justapi/justapi \
44
+ --set image.repository=gcr.io/$PROJECT_ID/justapi-app \
45
+ --set image.tag=latest \
46
+ --set ingress.enabled=true \
47
+ --set ingress.host=api.example.com
48
+```
49
+
50
+## See Also
51
+
52
+- [Amazon EKS](/deployment/eks/) — Deploy on AWS
53
+- [Azure AKS](/deployment/aks/) — Deploy on Azure
54
+- [Kubernetes / Helm](/deployment/kubernetes-helm/) — Helm chart reference
0
55
▼docs_site/src/content/docs/deployment/production-checklist.md
+124-0
@@ -0,0 +1,124 @@
1
+---
2
+title: Production Checklist
3
+description: Essential settings and configuration for running JustAPI in production.
4
+---
5
+
6
+## 1. Build for Production
7
+
8
+```bash
9
+# Release build of the Rust extension
10
+maturin develop --release --manifest-path crates/justapi-py/Cargo.toml
11
+```
12
+
13
+`Cargo.toml` sets `panic = "abort"` in release mode — panics safely abort the process (no UB across PyO3 FFI).
14
+
15
+## 2. Process Supervision
16
+
17
+Run under a supervisor that restarts the process:
18
+
19
+```ini
20
+# systemd unit
21
+[Service]
22
+ExecStart=/srv/app/venv/bin/python -m myapp
23
+Restart=always
24
+RestartSec=1
25
+StartLimitIntervalSec=10
26
+StartLimitBurst=5
27
+```
28
+
29
+For Kubernetes, set `restartPolicy: Always` with liveness and readiness probes.
30
+
31
+## 3. TLS Termination
32
+
33
+**Recommended:** Terminate TLS at an edge proxy (nginx, Caddy, cloud LB):
34
+
35
+```nginx
36
+server {
37
+ listen 443 ssl;
38
+ location / {
39
+ proxy_pass http://127.0.0.1:8000;
40
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
41
+ proxy_set_header X-Forwarded-Proto $scheme;
42
+ client_max_body_size 1m;
43
+ }
44
+}
45
+```
46
+
47
+## 4. Request Body Size
48
+
49
+Set the smallest value your endpoints allow:
50
+
51
+```python
52
+app.run("0.0.0.0:8000", max_body_size=1024 * 1024) # 1 MiB
53
+```
54
+
55
+Bodies over the limit receive **413 Payload Too Large**.
56
+
57
+## 5. Security Headers
58
+
59
+```python
60
+app.enable_secure_headers(with_hsts=True)
61
+app.add_cors(
62
+ allow_origins=["https://yourdomain.com"],
63
+ allow_methods=["GET", "POST"],
64
+)
65
+```
66
+
67
+CORS is deny-by-default — no permissive `*` unless you configure it.
68
+
69
+## 6. Health Checks
70
+
71
+```python
72
+app.register_health_check("postgres", lambda: db_ok())
73
+
74
+# Endpoints:
75
+# GET /health → liveness probe (200 = OK)
76
+# GET /ready → readiness probe (200 = all deps healthy)
77
+# GET /live → lightweight liveness alias
78
+```
79
+
80
+## 7. Metrics
81
+
82
+```bash
83
+# Scrape /metrics with Prometheus
84
+curl http://localhost:8000/metrics
85
+```
86
+
87
+Key signals: request count by route/status, p50/p95/p99 latency, error ratios.
88
+
89
+## 8. Timeouts
90
+
91
+```bash
92
+justapi serve --timeout 30 # Request timeout in seconds
93
+```
94
+
95
+Keep proxy and JustAPI timeouts aligned to avoid spurious 504s.
96
+
97
+## 9. Graceful Shutdown
98
+
99
+`run()` installs SIGINT/SIGTERM handlers. On signal, it:
100
+1. Stops accepting new connections
101
+2. Drains in-flight requests
102
+3. Calls plugin shutdown hooks
103
+4. Exits cleanly
104
+
105
+Ensure your supervisor sends **SIGTERM** (not SIGKILL) for clean drains.
106
+
107
+## 10. Pre-Flight Checklist
108
+
109
+- [ ] Release build (`maturin develop --release`)
110
+- [ ] Supervisor with `Restart=always` / `restartPolicy: Always`
111
+- [ ] TLS terminated at proxy (or native TLS configured)
112
+- [ ] `max_body_size` set to the smallest value your endpoints allow
113
+- [ ] `enable_secure_headers()` called; CORS explicitly configured
114
+- [ ] `/live` + `/ready` wired to liveness/readiness probes
115
+- [ ] `/metrics` scraped; alerts on error ratio + p99
116
+- [ ] Request timeout set; proxy idle timeout ≥ JustAPI timeout
117
+- [ ] Graceful shutdown verified (SIGTERM drains cleanly)
118
+- [ ] No request bodies logged in production
119
+
120
+## See Also
121
+
122
+- [Docker](/deployment/docker/) — Container deployment
123
+- [Kubernetes / Helm](/deployment/kubernetes-helm/) — K8s deployment
124
+- [Performance Tuning](/advanced/performance-tuning/) — Optimize your app
0
125
▼docs_site/src/content/docs/deployment/railway.md
+45-0
@@ -0,0 +1,45 @@
1
+---
2
+title: Railway
3
+description: Deploy JustAPI to Railway for zero-config cloud deployment.
4
+---
5
+
6
+## 1. Create `railway.json`
7
+
8
+```json
9
+{
10
+ "build": {
11
+ "builder": "DOCKERFILE"
12
+ },
13
+ "deploy": {
14
+ "restartPolicyType": "ALWAYS",
15
+ "numReplicas": 2
16
+ }
17
+}
18
+```
19
+
20
+## 2. Configure Environment
21
+
22
+Set these environment variables in Railway dashboard:
23
+
24
+| Variable | Description |
25
+|---|---|
26
+| `PORT` | Usually set automatically to 8080 |
27
+| `RUST_LOG` | `info` |
28
+| `DATABASE_URL` | PostgreSQL connection string |
29
+| `REDIS_URL` | Redis connection string |
30
+
31
+## 3. Deploy
32
+
33
+```bash
34
+railway login
35
+railway init
36
+railway up
37
+```
38
+
39
+Or connect via GitHub — Railway auto-deploys on push.
40
+
41
+## See Also
42
+
43
+- [Fly.io](/deployment/flyio/) — Deploy on Fly.io
44
+- [Docker](/deployment/docker/) — Container setup
45
+- [Production Checklist](/deployment/production-checklist/) — Production readiness
0
46