Monorepo consolidation: workspace, shared types, transport plans, docker/swam assets

gateway/DEPLOYMENT.md

@@ -0,0 +1,62 @@
+# Deployment Notes
+
+## Swarm Ingress and TLS
+
+Gateway exposes:
+- HTTP: `:8080`
+- gRPC: `:8081`
+
+Recommended pattern in Swarm:
+- Terminate TLS at an ingress proxy (Traefik / Nginx / Envoy) on the overlay network.
+- Route HTTP and gRPC to the Gateway service by port.
+- Prefer L7 routing (Host + Path for HTTP, SNI for gRPC) and keep the Swarm routing mesh disabled unless you explicitly want it.
+
+## Secrets
+
+The Swarm stack expects these secrets to exist:
+- `gateway_jwt_secrets` (comma-separated or newline-separated signing secrets)
+- `google_oidc_client_id`
+- `google_oidc_client_secret`
+
+The container reads them via:
+- `GATEWAY_JWT_SECRETS_FILE`
+- `GOOGLE_OIDC_CLIENT_ID_FILE`
+- `GOOGLE_OIDC_CLIENT_SECRET_FILE`
+
+## Internal mTLS (Optional)
+
+Gateway can be configured to use mTLS when calling internal upstreams.
+
+HTTP upstream (reqwest):
+- `GATEWAY_INTERNAL_CA_CERT_PEM_FILE`
+- `GATEWAY_INTERNAL_IDENTITY_PEM_FILE` (combined cert + key PEM)
+
+gRPC upstream (tonic):
+- `GATEWAY_INTERNAL_GRPC_TLS` = `true|false` (or use `https://` upstream URLs)
+- `GATEWAY_INTERNAL_GRPC_CA_CERT_PEM_FILE`
+- `GATEWAY_INTERNAL_GRPC_CLIENT_CERT_PEM_FILE`
+- `GATEWAY_INTERNAL_GRPC_CLIENT_KEY_PEM_FILE`
+
+## HA Validation (Manual)
+
+With `gateway` running at `replicas: 2`:
+- Verify `/ready` stays healthy during rolling updates.
+- Verify refresh rotation works across replicas (no sticky sessions):
+  - Sign in → refresh from one replica → refresh again against the other replica and confirm the old token is rejected.
+- Verify admin IAM changes are visible across replicas:
+  - Create a role/assignment via `/admin/iam` on one replica → call an authorized endpoint via the other replica.
+
+### Suggested Procedure
+
+1. Deploy the stack:
+   - `docker stack deploy -c swarm/stacks/platform.yml cloudlysis`
+2. Confirm `gateway` has 2 running tasks:
+   - `docker service ps cloudlysis_gateway`
+3. Smoke readiness (at least one replica reachable through ingress):
+   - `curl -fsS http://localhost:8080/ready`
+4. Refresh across replicas:
+   - Run the refresh flow twice while forcing traffic to different replicas (hostnames or per-task published ports if you use an ingress proxy).
+5. Rolling update guard:
+   - Update the image tag and redeploy, then watch:
+     - `docker service ps cloudlysis_gateway`
+     - `curl -fsS http://localhost:8080/ready` in a loop