swadhin / justapi public

p5a-c: add Docker, Kubernetes/Helm, Cloudflare Pages deployment guides

swadhinbiswas committed 3 months ago

18ed146

1 parent 578b09d

commit 18ed146

3 files changed

+251 -19

Files

docs_site

src

content

docs

deployment

cloudflare-pages.md +26 -19 docker.md +123 kubernetes-helm.md +102

Showing 3 changed files+251-19

docs_site/src/content/docs/deployment/cloudflare-pages.md docs_site/src/content/docs/deployment/docker.md docs_site/src/content/docs/deployment/kubernetes-helm.md

▼docs_site/src/content/docs/deployment/cloudflare-pages.md

+26-19

@@ -1,37 +1,33 @@
1	1	---
2		-title: Cloudflare Pages Deployment Guide
3		-description: Deploy your JustAPI Astro documentation site to Cloudflare Pages with zero-config CI/CD.
	2	+title: Cloudflare Pages Deployment
	3	+description: Deploy your JustAPI documentation site to Cloudflare Pages.
4	4	---
5	5
6		-This documentation site is built with Astro and Starlight, making it 100% static-site generator (SSG) compatible and ready for instant deployment on Cloudflare Pages.
	6	+This documentation site is built with Astro and Starlight, making it 100% static-site generator (SSG) compatible.
7	7
8	8	## Method 1: Git Integration (Recommended)
9	9
10		-1. Push your repository to GitHub or GitLab.
11		-2. Log into the Cloudflare Dashboard and navigate to Workers & Pages.
12		-3. Click Create Application → Pages → Connect to Git.
13		-4. Select your `JustAPI` repository and choose the branch (e.g. `main` or `initial-setup`).
14		-5. Configure the Build Settings:
15		- * Framework Preset: `Astro`
16		- * Root Directory: `docs_site`
17		- * Build Command: `npm run build`
18		- * Build Output Directory: `dist`
19		-6. Click Save and Deploy. Cloudflare Pages will automatically build and publish your site with free global CDN edge distribution and SSL!
	10	+1. Push your repository to GitHub or GitLab
	11	+2. Log into Cloudflare Dashboard → Workers & Pages → Create Application → Pages → Connect to Git
	12	+3. Select your repository and branch
	13	+4. Configure build settings:
	14	+ - Framework Preset: Astro
	15	+ - Root Directory: `docs_site`
	16	+ - Build Command: `npm run build`
	17	+ - Build Output Directory: `dist`
	18	+5. Click Save and Deploy
20	19
21		-## Method 2: Direct CLI Deployment (`wrangler`)
	20	+Cloudflare Pages automatically builds and publishes with free global CDN, SSL, and edge distribution.
22	21
23		-Deploy directly from your local terminal using Cloudflare's `wrangler` CLI:
	22	+## Method 2: CLI Deployment (wrangler)
24	23
25	24	```bash
26		-# Build the static site output
27	25	cd docs_site
28	26	npm run build
29		-
30		-# Deploy to Cloudflare Pages
31	27	npx wrangler pages deploy dist --project-name=justapi-docs
32	28	```
33	29
34		-## Cloudflare Pages Configuration (`wrangler.jsonc`)
	30	+## Cloudflare Pages Configuration
35	31
36	32	```json
37	33	{
@@ -39,3 +35,14 @@ npx wrangler pages deploy dist --project-name=justapi-docs
39	35	"pages_build_output_dir": "./dist"
40	36	}
41	37	```
	38	+
	39	+## Custom Domain
	40	+
	41	+1. Go to Cloudflare Pages → your project → Custom Domains
	42	+2. Add your domain (e.g., `docs.justapi.dev`)
	43	+3. Update DNS records
	44	+
	45	+## See Also
	46	+
	47	+- [Docker](/deployment/docker/) — Container deployment
	48	+- [Kubernetes / Helm](/deployment/kubernetes-helm/) — K8s deployment
42	49

▼docs_site/src/content/docs/deployment/docker.md

+123-0

@@ -0,0 +1,123 @@
	1	+---
	2	+title: Docker & Docker Compose
	3	+description: Containerize your JustAPI application for development and production.
	4	+---
	5	+
	6	+## Multi-Stage Dockerfile
	7	+
	8	+The repository includes a production-ready multi-stage Dockerfile:
	9	+
	10	+```dockerfile
	11	+# Stage 1: Build Rust CLI binary and Python wheel
	12	+FROM rust:1.75-bookworm AS builder
	13	+
	14	+RUN apt-get update && apt-get install -y \
	15	+ libssl-dev pkg-config python3 python3-pip python3-venv
	16	+
	17	+WORKDIR /app
	18	+COPY Cargo.toml Cargo.lock ./
	19	+COPY crates/ crates/
	20	+COPY python/ python/
	21	+
	22	+RUN python3 -m venv /opt/venv
	23	+ENV PATH="/opt/venv/bin:$PATH"
	24	+RUN pip install maturin
	25	+RUN cargo build --release -p justapi-cli --features tls,compression
	26	+RUN maturin build -m crates/justapi-py/Cargo.toml --release -o wheels/
	27	+
	28	+# Stage 2: Minimal runtime
	29	+FROM python:3.12-slim-bookworm
	30	+RUN apt-get update && apt-get install -y ca-certificates libssl3
	31	+
	32	+WORKDIR /app
	33	+COPY --from=builder /app/target/release/justapi /usr/local/bin/justapi
	34	+COPY --from=builder /app/wheels /tmp/wheels
	35	+RUN pip install --no-cache-dir /tmp/wheels/*.whl
	36	+
	37	+COPY . .
	38	+EXPOSE 8080
	39	+CMD ["python", "app.py"]
	40	+```
	41	+
	42	+### Build the Image
	43	+
	44	+```bash
	45	+docker build -t my-justapi-app .
	46	+docker run -p 8080:8080 my-justapi-app
	47	+```
	48	+
	49	+## Docker Compose (Development)
	50	+
	51	+```yaml
	52	+version: "3.9"
	53	+services:
	54	+ justapi:
	55	+ build: .
	56	+ ports:
	57	+ - "8080:8080"
	58	+ environment:
	59	+ - RUST_LOG=info
	60	+ - DATABASE_URL=postgres://justapi:justapi@db:5432/justapi
	61	+ depends_on:
	62	+ db:
	63	+ condition: service_healthy
	64	+
	65	+ db:
	66	+ image: postgres:16-alpine
	67	+ environment:
	68	+ POSTGRES_USER: justapi
	69	+ POSTGRES_PASSWORD: justapi
	70	+ POSTGRES_DB: justapi
	71	+ healthcheck:
	72	+ test: ["CMD-SHELL", "pg_isready -U justapi"]
	73	+ interval: 5s
	74	+ timeout: 5s
	75	+ retries: 5
	76	+```
	77	+
	78	+```bash
	79	+docker compose up -d
	80	+```
	81	+
	82	+## OpenTelemetry Stack
	83	+
	84	+Generated projects include `docker-compose.otel.yml`:
	85	+
	86	+```yaml
	87	+services:
	88	+ jaeger:
	89	+ image: jaegertracing/all-in-one:latest
	90	+ ports:
	91	+ - "16686:16686" # UI
	92	+ - "4318:4318" # OTLP HTTP
	93	+```
	94	+
	95	+## Production Image Optimizations
	96	+
	97	+1. Use `python:3.12-slim` — Small image (~120 MB)
	98	+2. Set `panic = "abort"` — Already configured in Cargo.toml
	99	+3. Run as non-root — Use `USER nobody` or create an app user
	100	+4. Add HEALTHCHECK — Use `/health` endpoint
	101	+5. Use `.dockerignore` — Exclude target/, .git/, __pycache__/
	102	+
	103	+### Example Production Dockerfile Snippet
	104	+
	105	+```dockerfile
	106	+FROM python:3.12-slim-bookworm
	107	+RUN adduser --disabled-password --gecos '' appuser
	108	+WORKDIR /app
	109	+COPY --from=builder /app/target/release/justapi /usr/local/bin/justapi
	110	+COPY --from=builder /app/wheels /tmp/wheels
	111	+RUN pip install --no-cache-dir /tmp/wheels/*.whl && rm -rf /tmp/wheels
	112	+COPY app.py .
	113	+USER appuser
	114	+EXPOSE 8080
	115	+HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"
	116	+CMD ["python", "app.py"]
	117	+```
	118	+
	119	+## See Also
	120	+
	121	+- [Kubernetes / Helm](/deployment/kubernetes-helm/) — Orchestrate with K8s
	122	+- [Production Checklist](/deployment/production-checklist/) — Production readiness
	123	+- [Docker Compose File](https://github.com/swadhinbiswas/JustAPI/blob/main/docker-compose.yml)
0	124

▼docs_site/src/content/docs/deployment/kubernetes-helm.md

+102-0

@@ -0,0 +1,102 @@
	1	+---
	2	+title: Kubernetes & Helm
	3	+description: Deploy JustAPI on Kubernetes using the official Helm chart.
	4	+---
	5	+
	6	+## Prerequisites
	7	+
	8	+- Kubernetes cluster (v1.24+)
	9	+- Helm v3.8+
	10	+- kubectl configured
	11	+
	12	+## Quick Install
	13	+
	14	+```bash
	15	+# Add the JustAPI Helm repository
	16	+helm repo add justapi https://justapi.dev/charts
	17	+helm repo update
	18	+
	19	+# Install
	20	+helm upgrade --install my-app justapi/justapi \
	21	+ --set image.repository=myregistry/my-app \
	22	+ --set image.tag=latest
	23	+```
	24	+
	25	+## Helm Chart Structure
	26	+
	27	+```
	28	+helm/justapi/
	29	+├── Chart.yaml
	30	+├── values.yaml
	31	+├── templates/
	32	+│ ├── deployment.yaml
	33	+│ ├── service.yaml
	34	+│ ├── ingress.yaml
	35	+│ ├── hpa.yaml
	36	+│ ├── configmap.yaml
	37	+│ ├── secret.yaml
	38	+│ └── serviceaccount.yaml
	39	+└── _helpers.tpl
	40	+```
	41	+
	42	+## Configuration Reference
	43	+
	44	+\| Parameter \| Default \| Description \|
	45	+\|---\|---\|---\|
	46	+\| `replicaCount` \| `2` \| Number of replicas \|
	47	+\| `image.repository` \| — \| Container image \|
	48	+\| `image.tag` \| `latest` \| Image tag \|
	49	+\| `image.pullPolicy` \| `Always` \| Pull policy \|
	50	+\| `service.port` \| `8080` \| Service port \|
	51	+\| `ingress.enabled` \| `false` \| Enable ingress \|
	52	+\| `ingress.host` \| — \| Ingress hostname \|
	53	+\| `ingress.tls` \| `false` \| Enable TLS \|
	54	+\| `resources.limits.cpu` \| `"1000m"` \| CPU limit \|
	55	+\| `resources.limits.memory` \| `"512Mi"` \| Memory limit \|
	56	+\| `hpa.enabled` \| `true` \| Enable HPA \|
	57	+\| `hpa.minReplicas` \| `2` \| Min pods \|
	58	+\| `hpa.maxReplicas` \| `10` \| Max pods \|
	59	+\| `hpa.targetCPUUtilization` \| `70` \| CPU target % \|
	60	+\| `config.rustLog` \| `"info"` \| RUST_LOG value \|
	61	+\| `config.otelServiceName` \| `"justapi"` \| OTel service name \|
	62	+\| `secret.databaseUrl` \| — \| DB connection string \|
	63	+\| `secret.redisUrl` \| — \| Redis connection string \|
	64	+
	65	+## Deployment with Custom Configuration
	66	+
	67	+```bash
	68	+helm upgrade --install my-app justapi/justapi \
	69	+ --set replicaCount=4 \
	70	+ --set resources.limits.cpu="2000m" \
	71	+ --set resources.limits.memory="1Gi" \
	72	+ --set hpa.targetCPUUtilization=50 \
	73	+ --set config.rustLog="debug" \
	74	+ --set ingress.enabled=true \
	75	+ --set ingress.host="api.example.com"
	76	+```
	77	+
	78	+## Ingress with TLS
	79	+
	80	+```yaml
	81	+ingress:
	82	+ enabled: true
	83	+ host: api.example.com
	84	+ tls: true
	85	+ className: nginx
	86	+ annotations:
	87	+ cert-manager.io/cluster-issuer: letsencrypt-prod
	88	+```
	89	+
	90	+## Health Check Probes
	91	+
	92	+The chart configures Kubernetes probes automatically:
	93	+
	94	+- Liveness: `GET /health` — Is the process alive?
	95	+- Readiness: `GET /ready` — Is the app ready to serve traffic?
	96	+- Startup: `GET /health` — Has the app finished starting?
	97	+
	98	+## See Also
	99	+
	100	+- [Docker](/deployment/docker/) — Containerize your app
	101	+- [Production Checklist](/deployment/production-checklist/) — Production readiness
	102	+- [Helm Chart Source](https://github.com/swadhinbiswas/JustAPI/tree/main/helm/justapi)
0	103