chore: adding docs
This commit is contained in:
Daniel Noulet
parent
23816d00f7
commit
81c5112409
39 changed files with 7257 additions and 2 deletions
108
data/docs/go-places-infrastructure.md
Normal file
108
data/docs/go-places-infrastructure.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
<!-- go-doc:generated:begin source=go-places:INFRASTRUCTURE.md signature=0fcd11f2310a851002924fdb59e5ad85 generated=2026-10-05 18:14 UTC -->
|
||||
Imported from INFRASTRUCTURE.md in the go-places repository.
|
||||
|
||||
---
|
||||
|
||||
# 🏰 Ecosystem Installation Playbook: End-to-End Guide
|
||||
**Target System:** Kubernetes Cluster managed by Rancher
|
||||
**Ecosystem Components:** go-places (this repository), go-loose, go-guess, go-tell, etc.
|
||||
**Goal:** Achieve a "Press Start" configuration where the entire stack runs reliably, persistently, and securely.
|
||||
**Author:** AI Assistant
|
||||
**Date Generated:** 2026-10-03
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ IMPORTANT WARNINGS & SAFETY CHECKLIST
|
||||
*** DO NOT PROCEED WITHOUT READING THIS SECTION. ***
|
||||
|
||||
* **Destructive Actions:** This guide includes commands to prune/reset system environments (e.g., Docker). Ensure all necessary repositories are backed up *before* executing Phase 0 cleanup steps.
|
||||
* **Security:** All networking relies on the Ingress Controller and Cert-Manager for TLS termination. Ensure your DNS points correctly to the Ingress LoadBalancer IP.
|
||||
* **Service Mesh:** An innovative Service Mesh (e.g., Istio/Linkerd) will be implemented to handle mTLS, traffic routing, and observability. This adds significant complexity; proceed with caution.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Phase 0: Prerequisites, Cleanup, and Backup (The "Start From Scratch" State)
|
||||
|
||||
This phase ensures a known, clean state. **Execute these steps only when ready for a fresh deployment.**
|
||||
|
||||
### 0.1 Tool Installation
|
||||
* Install Docker Engine.
|
||||
* Install Helm 3.
|
||||
* Install `kubectl` and configure access to the target K8s cluster (`kubectl config use-context <target-cluster>`).
|
||||
|
||||
### 0.2 System Cleanup (Mandatory for Clean Slate)
|
||||
* *Action:* Run the following commands to stop all services and remove all unused images/volumes.
|
||||
* *Command:* `docker stop $(docker ps -q) && docker rm $(docker ps -aq) && docker image prune -f && docker system prune -a -f`
|
||||
|
||||
### 0.3 Repository Persistence Setup (Forgejo Mounts)
|
||||
To ensure code history persists across host reboots, we must map local paths to persistent volumes.
|
||||
* *Action:* Identify the root path for the source code (e.g., `/home/dnoulet/go/`).
|
||||
* *Command (Example):* Configure the K8s PersistentVolumeClaim (PVC) for Forgejo to mount at `/mnt/forgejo-repo`.
|
||||
* *Guidance:* Refer to the Forgejo installation guide for exact PVC definitions.
|
||||
|
||||
## 🗺️ Phase 1: Core Infrastructure Deployment (The Foundation)
|
||||
|
||||
This phase sets up the networking and security backbone before deploying any application logic.
|
||||
|
||||
### 1.1 Service Mesh Implementation
|
||||
* *Recommendation:* Implement **Istio** for a robust Service Mesh.
|
||||
* *Action:* Apply Istio's base installation manifest (`istioctl install --set profile=default`).
|
||||
|
||||
### 1.2 TLS Management (Cert-Manager)
|
||||
* *Action:* Deploy `cert-manager`. This allows dynamic issuance of certificates for external traffic.
|
||||
* *Resource:* Define the necessary `Certificate` resources referencing your public domains.
|
||||
|
||||
### 1.3 Entry Point (Ingress Controller)
|
||||
* *Action:* Deploy the Ingress Controller (e.g., Nginx Ingress Controller).
|
||||
* *Configuration:* Configure the Ingress resource to reference the `Certificate` Secret generated by Cert-Manager.
|
||||
|
||||
## 🛠️ Phase 2: Application Build and Deployment (The Go Code)
|
||||
|
||||
This phase builds the Go services and deploys them into the cluster, using the Service Mesh for communication.
|
||||
|
||||
### 2.1 Building Docker Images
|
||||
* *Action:* Navigate to the service root and build the image.
|
||||
* *Command:* `make build`, then `docker build -t go-places:latest .` (build context is the repository root).
|
||||
|
||||
### 2.2 Deploying Services via Helm
|
||||
* **Order of Deployment is Critical:**
|
||||
1. **`go-loose` (Auth):** Deploy first as it is a core dependency.
|
||||
`helm upgrade --install go-loose ./charts/go-loose -n dev`
|
||||
2. **`go-places`:** Deploy next. It reaches `go-loose` only by verifying that service's JWTs, so there is no service URL to wire up; set `AUTH_MODE=jwt` and `JWT_SECRET` to the shared signing secret.
|
||||
`helm upgrade --install go-places ./charts/api -n dev`
|
||||
3. **`go-guess`, `go-tell`:** Repeat the above for all other applications.
|
||||
|
||||
## ✅ Phase 3: Verification and Finalization
|
||||
|
||||
* **Service Health Check:** Verify all pods are running (`kubectl get pods -n dev`).
|
||||
* **Dependency Checks:** `curl -fsS https://api.yourdomain.com/healthz` and `curl -fsS https://api.yourdomain.com/readyz`. Both are unauthenticated so a probe or a quick `curl` works; `/readyz` additionally pings SQLite and answers `503` when the database is unreachable.
|
||||
* **API Functionality Test:** Send an authenticated request. The GraphQL executor only answers `POST`, so a browser link cannot leak data:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer $GO_LOOSE_TOKEN" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"query":"{ places { id title } }"}' \
|
||||
https://api.yourdomain.com/graphql
|
||||
```
|
||||
|
||||
* **Media Check:** `curl -I https://api.yourdomain.com/media/<key>` should return `200` and `Cache-Control: public, max-age=31536000, immutable`. Media is deliberately unauthenticated so `<img>` tags work; if that is not acceptable for your data, put the Ingress in front of it with an auth subrequest.
|
||||
|
||||
## 🌐 Phase 4: Web Front-end
|
||||
|
||||
The React app in `web/` is a static bundle. It is **not** served by the `go-places` image and **not** deployed by `charts/api`; the API has no front-end assets. Two ways to publish it:
|
||||
|
||||
* **Recommended:** build once and serve from a static host (or an nginx Deployment) on a subdomain, e.g. `https://places.yourdomain.com`. Point it at the API by configuring the CORS origins allowed by the Ingress, or serve it under the same host so the browser makes same-origin requests.
|
||||
* **Quick path:** serve `web/dist` from any web server and use the Vite dev proxy locally (see `DEVELOPER.md`), which avoids CORS entirely because everything is same-origin.
|
||||
|
||||
The client needs two things from its build environment:
|
||||
|
||||
| Variable | Meaning |
|
||||
| --- | --- |
|
||||
| `VITE_API_BASE` | Optional. Base URL for the API when it is not same-origin. Empty means same-origin. |
|
||||
| `VITE_API_TOKEN` | Optional. A token baked into the bundle. Leave unset and let the user paste a go-loose token into the "Set token" field in the UI. |
|
||||
|
||||
Baking a token into a public bundle publishes it to every visitor, so only do that for a throwaway demo.
|
||||
|
||||
---
|
||||
*End of Initial Playbook Draft.*
|
||||
<!-- go-doc:generated:end -->
|
||||
Loading…
Add table
Add a link
Reference in a new issue