cloud-deploy-blueprint

Name: cloud-deploy-blueprint
Author: mjunaidca

26stars11forks

How to install cloud-deploy-blueprint?

mjunaidca/mjs-agent-skills/cloud-deploy-blueprint

$npx -y skills add mjunaidca/mjs-agent-skills --skill cloud-deploy-blueprint

Installs into the current project.

Summary

End-to-end cloud deployment skill for Kubernetes (AKS/GKE/DOKS) with CI/CD pipelines. Covers managed services integration (Neon, Upstash), ingress configuration, SSL certificates, GitHub Actions workflows with selective builds, and Next.js build-time vs runtime environment handli

Files · 1

View on GitHub

SKILL.md

1	# Cloud Deploy Blueprint
2
3	## Overview
4
5	This skill captures the complete knowledge for deploying a multi-service application to cloud Kubernetes, based on battle-tested learnings from deploying TaskFlow (5 microservices) to Azure AKS.
6
7	## When to Use
8
9	- Deploying to AKS, GKE, or DOKS
10	- Setting up CI/CD with GitHub Actions
11	- Integrating managed services (Neon PostgreSQL, Upstash Redis)
12	- Configuring ingress with SSL certificates
13	- Handling Next.js `NEXT_PUBLIC_*` variables in Docker/K8s
14
15	## Architecture Pattern
16
17	```
18	INTERNET
19	│
20	▼
21	┌─────────────────┐
22	│ Load Balancer │ (Single Public IP)
23	└────────┬────────┘
24	│
25	┌────────▼────────┐
26	│ Ingress (Traefik│ Routes by subdomain
27	│ or nginx) │
28	└────────┬────────┘
29	│
30	┌────────────────────┼────────────────────┐
31	│ │ │
32	▼ ▼ ▼
33	┌──────────┐ ┌──────────┐ ┌──────────┐
34	│ Web │ │ SSO │ │ MCP │
35	│ (PUBLIC) │ │ (PUBLIC) │ │ (PUBLIC) │
36	└────┬─────┘ └────┬─────┘ └────┬─────┘
37	│ │ │
38	│ ┌────▼─────┐ │
39	└──────────────► API ◄─────────────┘
40	│(INTERNAL)│
41	└────┬─────┘
42	│
43	┌────────────┴────────────┐
44	▼ ▼
45	┌─────────────┐ ┌─────────────┐
46	│ Neon │ │ Upstash │
47	│ (Postgres) │ │ (Redis) │
48	│ EXTERNAL │ │ EXTERNAL │
49	└─────────────┘ └─────────────┘
50	```
51
52	## Critical Concept: Build-Time vs Runtime Variables
53
54	### The Problem
55
56	Next.js `NEXT_PUBLIC_` variables are embedded at build time*, not runtime. This means:
57
58	```dockerfile
59	# WRONG: Setting NEXT_PUBLIC_* at runtime does NOTHING
60	ENV NEXT_PUBLIC_API_URL=https://api.example.com
61
62	# RIGHT: Must be set as build ARG
63	ARG NEXT_PUBLIC_API_URL=https://api.example.com
64	ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
65	```
66
67	### The Solution
68
69	1. In Dockerfile: Use ARG for NEXT_PUBLIC_* variables
70	2. In CI/CD: Pass --build-arg with domain-specific values
71	3. In values.yaml: These are NOT runtime configurable
72
73	### Build-Time Variables (Next.js)
74
75	\| Service \| Variable \| Purpose \|
76	\|---------\|----------\|---------\|
77	\| Web \| `NEXT_PUBLIC_SSO_URL` \| SSO endpoint for browser OAuth \|
78	\| Web \| `NEXT_PUBLIC_API_URL` \| API endpoint for browser fetch \|
79	\| Web \| `NEXT_PUBLIC_APP_URL` \| App URL for redirects \|
80	\| SSO \| `NEXT_PUBLIC_BETTER_AUTH_URL` \| Better Auth URL for browser \|
81	\| SSO \| `NEXT_PUBLIC_CONTINUE_URL` \| Redirect after email verify \|
82
83	### Runtime Variables (ConfigMaps/Secrets)
84
85	\| Service \| Variable \| Source \|
86	\|---------\|----------\|--------\|
87	\| SSO \| `DATABASE_URL` \| Secret (Neon) \|
88	\| SSO \| `BETTER_AUTH_SECRET` \| Secret \|
89	\| API \| `SSO_URL` \| ConfigMap (internal K8s URL) \|
90	\| MCP \| `TASKFLOW_SSO_URL` \| ConfigMap (internal K8s URL) \|
91
92	## Internal K8s Service Names
93
94	Services communicate via K8s service names, NOT public URLs:
95
96	```yaml
97	# CORRECT - Internal communication
98	SSO_URL: http://sso-platform:3001
99	API_URL: http://taskflow-api:8000
100
101	# WRONG - Don't use public URLs for internal traffic
102	SSO_URL: https://sso.example.com
103	```
104
105	## GitHub Actions CI/CD Pattern
106
107	### Selective Builds with Path Filters
108
109	```yaml
110	jobs:
111	changes:
112	runs-on: ubuntu-latest
113	outputs:
114	api: ${{ steps.filter.outputs.api }}
115	web: ${{ steps.filter.outputs.web }}
116	steps:
117	- uses: dorny/paths-filter@v3
118	id: filter
119	with:
120	filters: \|
121	api:
122	- 'apps/api/**'
123	web:
124	- 'apps/web/**'
125
126	build-api:
127	needs: changes
128	if: needs.changes.outputs.api == 'true' \|\| github.event_name == 'workflow_dispatch'
129	```
130
131	### Next.js Build Args Pattern
132
133	```yaml
134	- name: Build and push (web)
135	uses: docker/build-push-action@v5
136	with:
137	build-args: \|
138	NEXT_PUBLIC_SSO_URL=https://sso.${{ vars.DOMAIN }}
139	NEXT_PUBLIC_API_URL=https://api.${{ vars.DOMAIN }}
140	NEXT_PUBLIC_APP_URL=https://${{ vars.DOMAIN }}
141	```
142
143	## GitHub Secrets & Variables
144
145	### Secrets (Sensitive)
146
147	```
148	NEON_SSO_DATABASE_URL
149	NEON_API_DATABASE_URL
150	NEON_CHATKIT_DATABASE_URL
151	NEON_NOTIFICATION_DATABASE_URL
152	UPSTASH_REDI

People who liked this also viewed

6 picks

Type

cloud-deploy-blueprint

26stars11forks

View on GitHub

How to install cloud-deploy-blueprint?

mjunaidca/mjs-agent-skills/cloud-deploy-blueprint

$npx -y skills add mjunaidca/mjs-agent-skills --skill cloud-deploy-blueprint

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Cloud Deploy Blueprint
2
3	## Overview
4
5	This skill captures the complete knowledge for deploying a multi-service application to cloud Kubernetes, based on battle-tested learnings from deploying TaskFlow (5 microservices) to Azure AKS.
6
7	## When to Use
8
9	- Deploying to AKS, GKE, or DOKS
10	- Setting up CI/CD with GitHub Actions
11	- Integrating managed services (Neon PostgreSQL, Upstash Redis)
12	- Configuring ingress with SSL certificates
13	- Handling Next.js `NEXT_PUBLIC_*` variables in Docker/K8s
14
15	## Architecture Pattern
16
17	```
18	INTERNET
19	│
20	▼
21	┌─────────────────┐
22	│ Load Balancer │ (Single Public IP)
23	└────────┬────────┘
24	│
25	┌────────▼────────┐
26	│ Ingress (Traefik│ Routes by subdomain
27	│ or nginx) │
28	└────────┬────────┘
29	│
30	┌────────────────────┼────────────────────┐
31	│ │ │
32	▼ ▼ ▼
33	┌──────────┐ ┌──────────┐ ┌──────────┐
34	│ Web │ │ SSO │ │ MCP │
35	│ (PUBLIC) │ │ (PUBLIC) │ │ (PUBLIC) │
36	└────┬─────┘ └────┬─────┘ └────┬─────┘
37	│ │ │
38	│ ┌────▼─────┐ │
39	└──────────────► API ◄─────────────┘
40	│(INTERNAL)│
41	└────┬─────┘
42	│
43	┌────────────┴────────────┐
44	▼ ▼
45	┌─────────────┐ ┌─────────────┐
46	│ Neon │ │ Upstash │
47	│ (Postgres) │ │ (Redis) │
48	│ EXTERNAL │ │ EXTERNAL │
49	└─────────────┘ └─────────────┘
50	```
51
52	## Critical Concept: Build-Time vs Runtime Variables
53
54	### The Problem
55
56	Next.js `NEXT_PUBLIC_` variables are embedded at build time*, not runtime. This means:
57
58	```dockerfile
59	# WRONG: Setting NEXT_PUBLIC_* at runtime does NOTHING
60	ENV NEXT_PUBLIC_API_URL=https://api.example.com
61
62	# RIGHT: Must be set as build ARG
63	ARG NEXT_PUBLIC_API_URL=https://api.example.com
64	ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
65	```
66
67	### The Solution
68
69	1. In Dockerfile: Use ARG for NEXT_PUBLIC_* variables
70	2. In CI/CD: Pass --build-arg with domain-specific values
71	3. In values.yaml: These are NOT runtime configurable
72
73	### Build-Time Variables (Next.js)
74
75	\| Service \| Variable \| Purpose \|
76	\|---------\|----------\|---------\|
77	\| Web \| `NEXT_PUBLIC_SSO_URL` \| SSO endpoint for browser OAuth \|
78	\| Web \| `NEXT_PUBLIC_API_URL` \| API endpoint for browser fetch \|
79	\| Web \| `NEXT_PUBLIC_APP_URL` \| App URL for redirects \|
80	\| SSO \| `NEXT_PUBLIC_BETTER_AUTH_URL` \| Better Auth URL for browser \|
81	\| SSO \| `NEXT_PUBLIC_CONTINUE_URL` \| Redirect after email verify \|
82
83	### Runtime Variables (ConfigMaps/Secrets)
84
85	\| Service \| Variable \| Source \|
86	\|---------\|----------\|--------\|
87	\| SSO \| `DATABASE_URL` \| Secret (Neon) \|
88	\| SSO \| `BETTER_AUTH_SECRET` \| Secret \|
89	\| API \| `SSO_URL` \| ConfigMap (internal K8s URL) \|
90	\| MCP \| `TASKFLOW_SSO_URL` \| ConfigMap (internal K8s URL) \|
91
92	## Internal K8s Service Names
93
94	Services communicate via K8s service names, NOT public URLs:
95
96	```yaml
97	# CORRECT - Internal communication
98	SSO_URL: http://sso-platform:3001
99	API_URL: http://taskflow-api:8000
100
101	# WRONG - Don't use public URLs for internal traffic
102	SSO_URL: https://sso.example.com
103	```
104
105	## GitHub Actions CI/CD Pattern
106
107	### Selective Builds with Path Filters
108
109	```yaml
110	jobs:
111	changes:
112	runs-on: ubuntu-latest
113	outputs:
114	api: ${{ steps.filter.outputs.api }}
115	web: ${{ steps.filter.outputs.web }}
116	steps:
117	- uses: dorny/paths-filter@v3
118	id: filter
119	with:
120	filters: \|
121	api:
122	- 'apps/api/**'
123	web:
124	- 'apps/web/**'
125
126	build-api:
127	needs: changes
128	if: needs.changes.outputs.api == 'true' \|\| github.event_name == 'workflow_dispatch'
129	```
130
131	### Next.js Build Args Pattern
132
133	```yaml
134	- name: Build and push (web)
135	uses: docker/build-push-action@v5
136	with:
137	build-args: \|
138	NEXT_PUBLIC_SSO_URL=https://sso.${{ vars.DOMAIN }}
139	NEXT_PUBLIC_API_URL=https://api.${{ vars.DOMAIN }}
140	NEXT_PUBLIC_APP_URL=https://${{ vars.DOMAIN }}
141	```
142
143	## GitHub Secrets & Variables
144
145	### Secrets (Sensitive)
146
147	```
148	NEON_SSO_DATABASE_URL
149	NEON_API_DATABASE_URL
150	NEON_CHATKIT_DATABASE_URL
151	NEON_NOTIFICATION_DATABASE_URL
152	UPSTASH_REDI

People who liked this also viewed

6 picks

Type