स्वचालित प्रोविजनिंग (Cloud)

यह दस्तावेज़ बताता है कि ग्राहक के सब्सक्राइब करने के बाद ~3-5 मिनट में RoqueOS Cloud VM कैसे शून्य से बनाई जाती है। उपयोग करने के लिए आपको कुछ भी समझने की आवश्यकता नहीं है — यह डिबग, समर्थन, या अपने व्यवसाय के लिए प्रवाह को अनुकूलित करना चाहने वालों के लिए तकनीकी संदर्भ है।

प्रवाह आरेख

1. ग्राहक /pricing पर "Cloud Pro सब्सक्राइब करें" क्लिक करता है
            │
            ▼
2. Stripe Checkout (ब्राज़ील) कार्ड/Pix संसाधित करता है
            │
            ▼
3. Stripe webhook → Cloud Function `provisionServer`
            │
            ▼
4. Cloud Function Hetzner API को कॉल करता है (CX32 VM बनाता है)
   + एफेमरल टोकन जेनरेट करता है (TTL 30 मिनट)
            │
            ▼
5. VM cloud-init के साथ बूट करता है जो निष्पादित करता है
   `curl https://roqueos.com.br/install.sh | bash`
   --customer-id, --tier, --provisioning-token,
   --provisioning-callback पास करता है
            │
            ▼
6. install.sh VM के अंदर चलता है:
   - Docker images खींचता है
   - स्थायी वॉल्यूम बनाता है
   - roqueos-server + sidecars (guacd, cloudflared) शुरू करता है
   - /health के 200 लौटाने का इंतजार करता है
   - admin key जेनरेट करने के लिए स्थानीय POST /admin/setup
   - {customerUid, token, apiKey, apiSecret} के साथ Firebase Functions को callback POST
            │
            ▼
7. Cloud Function `provisioningCallback` टोकन को मान्य करता है,
   सब्सक्रिप्शन को `active` मार्क करता है, क्रेडेंशियल सहेजता है (TTL 24h),
   SMTP के माध्यम से स्वागत ईमेल ट्रिगर करता है
            │
            ▼
8. ग्राहक URL + क्रेडेंशियल के साथ ईमेल प्राप्त करता है
   /app में लॉगिन पहले से ही नए सर्वर के लिए कॉन्फ़िगर

संलग्न घटक

Frontend (roqueos-front)

• src/pages/PricingPage.vue — "सब्सक्राइब" बटन Stripe Checkout की ओर ले जाता है
• functions/index.js — Cloud Functions provisionServer और provisioningCallback
• public/install.sh — roqueos-server के कैनोनिकल इंस्टॉलर का मिरर

Backend (roqueos-server)

• install/install.sh v1.1.0-cloud-callback — callback समर्थन के साथ एक-लाइनर इंस्टॉलर
• src/modules/admin/admin.controller.ts — आदर्शविधेय एंडपॉइंट POST /admin/setup (admin key जेनरेट)

बाहरी बुनियादी ढांचा

• Hetzner Cloud API (https://api.hetzner.cloud/v1) — सर्वर निर्माण
• Cloudflare API — सबडोमेन <id>.cloud.roqueos.com.br निर्माण (v1.2 नियोजित)
• Firebase Secret Manager — HCLOUD_TOKEN, PROVISIONER_SSH_KEY_ID, STANDARD_FIREWALL_ID स्टोर करता है
• Stripe Brasil — कार्ड/Pix के माध्यम से BRL checkout

Tier → Hetzner spec

RoqueOS Tier	Hetzner SKU	vCPU	RAM	SSD डिस्क	COGS €/माह
Starter	cx22	2 shared	4 GB	40 GB	4.51
Pro	cx32	4 shared	8 GB	80 GB	7.55
Power	ccx23	4 dedicated	16 GB	160 GB	31.20
Enterprise	ad-hoc	varia	varia	varia	varia

स्थान: फाल्केन्श्टीन, जर्मनी (fsn1)। छवि: ubuntu-22.04।

Cloud Function एंडपॉइंट

provisionServer (admin onCall)

ट्रिगर: Stripe webhook customer.subscription.created। आंतरिक रूप से यह https.onCall है जिसे context.auth.token.admin === true की आवश्यकता है।

Input:

{
  "customerUid": "abc123",
  "tier": "pro"
}

Output:

{
  "ok": true,
  "vmId": "12345678",
  "vmIp": "65.108.x.x",
  "provisioningToken": "<64 hex chars>",
  "callbackUrl": "https://southamerica-east1-roqueos.cloudfunctions.net/provisioningCallback",
  "tokenExpiresAt": 1716800000000
}

provisioningToken admin को केवल एक बार दिखाया जाता है (लॉग में नहीं रहता)। इसका SHA-256 हैश Firestore में subscriptions/{uid}.provisioning.tokenHash में TTL 30 मिनट के साथ रहता है।

provisioningCallback (HTTP सार्वजनिक)

ट्रिगर: नई बनाई गई VM install.sh के माध्यम से इस एंडपॉइंट पर POST कॉल करती है।

सार्वजनिक URL: https://southamerica-east1-roqueos.cloudfunctions.net/provisioningCallback

बिना Firebase auth के सार्वजनिक क्यों: नई VM के पास Firebase क्रेडेंशियल नहीं हैं। प्रमाणीकरण एफेमरल टोकन (एक-समय, SHA-256 हैश तुलना) द्वारा किया जाता है।

Input (POST JSON):

{
  "customerUid": "abc123",
  "token": "<64 hex chars>",
  "apiKey": "ros_xxxx",
  "apiSecret": "ros_secret_xxxx"
}

सत्यापन:

• पेलोड शेप (token + apiKey + apiSecret पर regex)
• tokenHash Firestore में रिकॉर्ड किए गए से मेल खाता है
• टोकन समाप्त नहीं हुआ
• सब्सक्रिप्शन अभी भी provisioning (पहले पूरा नहीं हुआ)

Output ok: 200 { "ok": true }Output एरर: HTTP 400/401/404/409/410 + { "error": "<code>" }

संभावित त्रुटियां:

• 400 missing_fields — अधूरा पेलोड
• 400 invalid_* — अमान्य शेप
• 401 token_mismatch — गलत टोकन (संभावित हमला, IP लॉग करता है)
• 404 subscription_not_found — customerUid मौजूद नहीं
• 409 already_completed — callback पहले से सफलतापूर्वक कॉल किया गया (dedup)
• 409 no_pending_provisioning — सब्सक्रिप्शन provisioning स्थिति में नहीं
• 410 token_expired — 30 मिनट से अधिक

cloud-init के install.sh flags

Cloud Function provisionServer एक user_data (cloud-init) जेनरेट करता है जो निष्पादित करता है:

#!/bin/bash
set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -y
apt-get install -y curl ca-certificates

curl -fsSL https://roqueos.com.br/install.sh | bash -s -- \
  --customer-id "${CUSTOMER_UID}" \
  --tier "${TIER}" \
  --provisioning-token "${TOKEN}" \
  --provisioning-callback "${CALLBACK_URL}" \
  --skip-prompts

4 flags --customer-id, --tier, --provisioning-token, --provisioning-callback install.sh v1.1.0-cloud-callback में जोड़े गए (स्क्रिप्ट के शीर्ष पर INSTALLER_VERSION)। जब सभी चार मौजूद होते हैं, इंस्टॉलर wait_for_server के healthy लौटने के बाद do_provisioning_callback() ट्रिगर करता है।

ऑपरेटर की ओर से मान्य करें

callback को मैन्युअल रूप से परीक्षण करें (नकली customerUid/token के साथ बदलें):

curl -sS -X POST \
  "https://southamerica-east1-roqueos.cloudfunctions.net/provisioningCallback" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerUid":"smoke-test",
    "token":"0000000000000000000000000000000000000000000000000000000000000000",
    "apiKey":"ros_smoketestkey",
    "apiSecret":"ros_secret_smoketest_secret_xyz"
  }'
# अपेक्षित: HTTP 404 {"error":"subscription_not_found"}

समस्या निवारण

लक्षण	संभावित कारण	समाधान
स्वागत ईमेल नहीं आया	Secret Manager में SMTP_HOST/USER/PASS गुम	gcloud secrets list --project=roqueos | grep SMTP + पुनः कॉन्फ़िगर
VM बनी लेकिन सब्सक्रिप्शन provisioning रही	install.sh VM के अंदर विफल (callback कॉल नहीं किया)	VM पर SSH: journalctl -u cloud-init -f + docker logs roqueos-server
Callback token_expired लौटाता है	प्रोविजनिंग में >30 मिनट लगे (VM धीमा)	टोकन + cloud-init पुनः जनरेट करने के लिए provisionServer फिर से चलाएं
Callback token_mismatch लौटाता है	बग या हमले का प्रयास	Function के लॉग में स्रोत IP देखें; यदि संदिग्ध, घुमाएं और सतर्क करें
Firestore दस्तावेज़ में vmIp: null	Hetzner API टाइमआउट या public_net के बिना प्रतिक्रिया	provisionServer पुनः प्रयास करें; लॉग gcloud functions logs read provisionServer

यहां प्रलेखित नहीं (लेकिन प्रासंगिक)

• सब्सक्रिप्शन का स्वचालित नवीकरण: Stripe customer.subscription.updated webhook के माध्यम से अकेले संभालता है। VM जीवित रहती है।
• रद्द: webhook customer.subscription.deleted → भविष्य का फ़ंक्शन decommissionServer जो VM रोकता है + अंतिम snapshot + "आपका डेटा 30 दिनों के लिए संरक्षित है" ईमेल।
• Tier अपग्रेड (Pro → Power): v1.2 नियोजित — संभवतः hcloud server change-type के माध्यम से माइग्रेशन।
• प्रति-ग्राहक Cloudflare Tunnel: नियोजित — आज प्रत्येक VM सार्वजनिक IP + पोर्ट 80/443 के माध्यम से उजागर। Tunnel edge SP के माध्यम से TLS जोड़ता है (BR के लिए कम विलंबता)।

क्रॉस संदर्भ

• RoqueOS Cloud अवलोकन — योजनाएं, मूल्य, तर्क
• सेल्फ-होस्ट इंस्टॉल — वही install.sh जो cloud-init के अंदर चलता है
• Server Admin Panel — नए प्रोविज़न किए गए सर्वर का प्रबंधन करने के लिए
• तकनीकी मेमोरी: hetzner_architecture_decision.md रिपो में (आंतरिक)