indraq_cli 2.2.4 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/README.md +158 -21
  2. package/cloud-api/.env.example +10 -0
  3. package/cloud-api/README.md +32 -3
  4. package/cloud-api/dist/index.js +840 -13
  5. package/cloud-api/package.json +5 -3
  6. package/cloud-api/scripts/check-dev-deps.mjs +11 -0
  7. package/cloud-api/sql/011_environment_internal_ipv4.sql +14 -0
  8. package/cloud-api/sql/012_mobile_ota.sql +139 -0
  9. package/cloud-api/src/index.ts +629 -13
  10. package/dist/cli/create-program.d.ts +1 -1
  11. package/dist/cli/create-program.d.ts.map +1 -1
  12. package/dist/cli/create-program.js +126 -46
  13. package/dist/cli/create-program.js.map +1 -1
  14. package/dist/cli/help-content.d.ts +1 -1
  15. package/dist/cli/help-content.d.ts.map +1 -1
  16. package/dist/cli/help-content.js +150 -32
  17. package/dist/cli/help-content.js.map +1 -1
  18. package/dist/index.js +55 -14
  19. package/dist/index.js.map +1 -1
  20. package/dist/modules/access/index.d.ts +1 -1
  21. package/dist/modules/access/index.d.ts.map +1 -1
  22. package/dist/modules/access/index.js +2 -3
  23. package/dist/modules/access/index.js.map +1 -1
  24. package/dist/modules/aws/commands/dns.command.js +4 -4
  25. package/dist/modules/aws/commands/dns.command.js.map +1 -1
  26. package/dist/modules/aws/index.d.ts +1 -1
  27. package/dist/modules/aws/index.d.ts.map +1 -1
  28. package/dist/modules/aws/index.js +18 -42
  29. package/dist/modules/aws/index.js.map +1 -1
  30. package/dist/modules/aws/services/route53-lookup.service.d.ts.map +1 -1
  31. package/dist/modules/aws/services/route53-lookup.service.js +2 -3
  32. package/dist/modules/aws/services/route53-lookup.service.js.map +1 -1
  33. package/dist/modules/aws/services/route53-sdk.d.ts +2 -0
  34. package/dist/modules/aws/services/route53-sdk.d.ts.map +1 -0
  35. package/dist/modules/aws/services/route53-sdk.js +12 -0
  36. package/dist/modules/aws/services/route53-sdk.js.map +1 -0
  37. package/dist/modules/cloud/commands/cloud.command.d.ts +2 -0
  38. package/dist/modules/cloud/commands/cloud.command.d.ts.map +1 -1
  39. package/dist/modules/cloud/commands/cloud.command.js +165 -17
  40. package/dist/modules/cloud/commands/cloud.command.js.map +1 -1
  41. package/dist/modules/cloud/commands/environment.command.d.ts.map +1 -1
  42. package/dist/modules/cloud/commands/environment.command.js +10 -6
  43. package/dist/modules/cloud/commands/environment.command.js.map +1 -1
  44. package/dist/modules/cloud/index.d.ts +1 -1
  45. package/dist/modules/cloud/index.d.ts.map +1 -1
  46. package/dist/modules/cloud/index.js +48 -52
  47. package/dist/modules/cloud/index.js.map +1 -1
  48. package/dist/modules/cloud/services/cloud-api.service.d.ts +1 -0
  49. package/dist/modules/cloud/services/cloud-api.service.d.ts.map +1 -1
  50. package/dist/modules/cloud/services/cloud-api.service.js +41 -1
  51. package/dist/modules/cloud/services/cloud-api.service.js.map +1 -1
  52. package/dist/modules/cloud/services/cloud-jenkins.service.d.ts +1 -0
  53. package/dist/modules/cloud/services/cloud-jenkins.service.d.ts.map +1 -1
  54. package/dist/modules/cloud/services/cloud-jenkins.service.js +5 -1
  55. package/dist/modules/cloud/services/cloud-jenkins.service.js.map +1 -1
  56. package/dist/modules/cloud/services/environment.service.d.ts +7 -1
  57. package/dist/modules/cloud/services/environment.service.d.ts.map +1 -1
  58. package/dist/modules/cloud/services/environment.service.js +5 -1
  59. package/dist/modules/cloud/services/environment.service.js.map +1 -1
  60. package/dist/modules/cloud/services/project-cloud.service.d.ts +2 -1
  61. package/dist/modules/cloud/services/project-cloud.service.d.ts.map +1 -1
  62. package/dist/modules/cloud/services/project-cloud.service.js +9 -1
  63. package/dist/modules/cloud/services/project-cloud.service.js.map +1 -1
  64. package/dist/modules/deploy/commands/build.command.d.ts +2 -1
  65. package/dist/modules/deploy/commands/build.command.d.ts.map +1 -1
  66. package/dist/modules/deploy/commands/build.command.js +120 -75
  67. package/dist/modules/deploy/commands/build.command.js.map +1 -1
  68. package/dist/modules/deploy/index.d.ts +1 -1
  69. package/dist/modules/deploy/index.d.ts.map +1 -1
  70. package/dist/modules/deploy/index.js +67 -36
  71. package/dist/modules/deploy/index.js.map +1 -1
  72. package/dist/modules/dockerfile/index.d.ts +1 -1
  73. package/dist/modules/dockerfile/index.d.ts.map +1 -1
  74. package/dist/modules/dockerfile/index.js +3 -2
  75. package/dist/modules/dockerfile/index.js.map +1 -1
  76. package/dist/modules/jenkins/commands/create-deployment.command.d.ts.map +1 -1
  77. package/dist/modules/jenkins/commands/create-deployment.command.js +7 -11
  78. package/dist/modules/jenkins/commands/create-deployment.command.js.map +1 -1
  79. package/dist/modules/jenkins/index.d.ts +1 -1
  80. package/dist/modules/jenkins/index.d.ts.map +1 -1
  81. package/dist/modules/jenkins/index.js +13 -22
  82. package/dist/modules/jenkins/index.js.map +1 -1
  83. package/dist/modules/mobile/commands/build-mobile.command.d.ts.map +1 -1
  84. package/dist/modules/mobile/commands/build-mobile.command.js +44 -5
  85. package/dist/modules/mobile/commands/build-mobile.command.js.map +1 -1
  86. package/dist/modules/mobile/commands/configure-mobile.command.d.ts.map +1 -1
  87. package/dist/modules/mobile/commands/configure-mobile.command.js +3 -12
  88. package/dist/modules/mobile/commands/configure-mobile.command.js.map +1 -1
  89. package/dist/modules/mobile/commands/mobile-environment.command.d.ts +5 -0
  90. package/dist/modules/mobile/commands/mobile-environment.command.d.ts.map +1 -0
  91. package/dist/modules/mobile/commands/mobile-environment.command.js +67 -0
  92. package/dist/modules/mobile/commands/mobile-environment.command.js.map +1 -0
  93. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts +6 -0
  94. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts.map +1 -0
  95. package/dist/modules/mobile/commands/mobile-prebuild.command.js +134 -0
  96. package/dist/modules/mobile/commands/mobile-prebuild.command.js.map +1 -0
  97. package/dist/modules/mobile/commands/ota.command.d.ts +8 -0
  98. package/dist/modules/mobile/commands/ota.command.d.ts.map +1 -0
  99. package/dist/modules/mobile/commands/ota.command.js +190 -0
  100. package/dist/modules/mobile/commands/ota.command.js.map +1 -0
  101. package/dist/modules/mobile/config/mobile-config.d.ts +26 -1
  102. package/dist/modules/mobile/config/mobile-config.d.ts.map +1 -1
  103. package/dist/modules/mobile/config/mobile-config.js +52 -9
  104. package/dist/modules/mobile/config/mobile-config.js.map +1 -1
  105. package/dist/modules/mobile/index.d.ts.map +1 -1
  106. package/dist/modules/mobile/index.js +27 -18
  107. package/dist/modules/mobile/index.js.map +1 -1
  108. package/dist/modules/mobile/services/jenkins-mobile.service.js +1 -1
  109. package/dist/modules/mobile/services/jenkins-mobile.service.js.map +1 -1
  110. package/dist/modules/mobile/services/mobile-cloud.service.d.ts +120 -0
  111. package/dist/modules/mobile/services/mobile-cloud.service.d.ts.map +1 -0
  112. package/dist/modules/mobile/services/mobile-cloud.service.js +53 -0
  113. package/dist/modules/mobile/services/mobile-cloud.service.js.map +1 -0
  114. package/dist/modules/mobile/services/ota-export.service.d.ts +14 -0
  115. package/dist/modules/mobile/services/ota-export.service.d.ts.map +1 -0
  116. package/dist/modules/mobile/services/ota-export.service.js +68 -0
  117. package/dist/modules/mobile/services/ota-export.service.js.map +1 -0
  118. package/dist/modules/mobile/services/ota-setup.service.d.ts +18 -0
  119. package/dist/modules/mobile/services/ota-setup.service.d.ts.map +1 -0
  120. package/dist/modules/mobile/services/ota-setup.service.js +374 -0
  121. package/dist/modules/mobile/services/ota-setup.service.js.map +1 -0
  122. package/dist/modules/prebuild/commands/prebuild.command.d.ts +3 -2
  123. package/dist/modules/prebuild/commands/prebuild.command.d.ts.map +1 -1
  124. package/dist/modules/prebuild/commands/prebuild.command.js +79 -56
  125. package/dist/modules/prebuild/commands/prebuild.command.js.map +1 -1
  126. package/dist/modules/prebuild/index.d.ts +1 -1
  127. package/dist/modules/prebuild/index.d.ts.map +1 -1
  128. package/dist/modules/prebuild/index.js +3 -2
  129. package/dist/modules/prebuild/index.js.map +1 -1
  130. package/dist/modules/proxy/commands/proxy.command.js +3 -3
  131. package/dist/modules/proxy/commands/proxy.command.js.map +1 -1
  132. package/dist/modules/proxy/index.d.ts +1 -1
  133. package/dist/modules/proxy/index.d.ts.map +1 -1
  134. package/dist/modules/proxy/index.js +8 -10
  135. package/dist/modules/proxy/index.js.map +1 -1
  136. package/dist/modules/scaffold/commands/init.command.d.ts.map +1 -1
  137. package/dist/modules/scaffold/commands/init.command.js +52 -18
  138. package/dist/modules/scaffold/commands/init.command.js.map +1 -1
  139. package/dist/modules/scaffold/index.d.ts +1 -1
  140. package/dist/modules/scaffold/index.d.ts.map +1 -1
  141. package/dist/modules/scaffold/index.js +4 -2
  142. package/dist/modules/scaffold/index.js.map +1 -1
  143. package/dist/modules/scaffold/project-topology.d.ts +14 -0
  144. package/dist/modules/scaffold/project-topology.d.ts.map +1 -0
  145. package/dist/modules/scaffold/project-topology.js +59 -0
  146. package/dist/modules/scaffold/project-topology.js.map +1 -0
  147. package/dist/modules/scaffold/types.d.ts +14 -1
  148. package/dist/modules/scaffold/types.d.ts.map +1 -1
  149. package/dist/modules/scopes/commands/scope.command.d.ts.map +1 -1
  150. package/dist/modules/scopes/commands/scope.command.js +18 -11
  151. package/dist/modules/scopes/commands/scope.command.js.map +1 -1
  152. package/dist/modules/scopes/index.d.ts +1 -1
  153. package/dist/modules/scopes/index.d.ts.map +1 -1
  154. package/dist/modules/scopes/index.js +15 -15
  155. package/dist/modules/scopes/index.js.map +1 -1
  156. package/dist/modules/setup/commands/setup.command.d.ts +2 -0
  157. package/dist/modules/setup/commands/setup.command.d.ts.map +1 -0
  158. package/dist/modules/setup/commands/setup.command.js +107 -0
  159. package/dist/modules/setup/commands/setup.command.js.map +1 -0
  160. package/dist/modules/setup/index.d.ts +3 -0
  161. package/dist/modules/setup/index.d.ts.map +1 -0
  162. package/dist/modules/setup/index.js +9 -0
  163. package/dist/modules/setup/index.js.map +1 -0
  164. package/dist/modules/users/index.d.ts +1 -1
  165. package/dist/modules/users/index.d.ts.map +1 -1
  166. package/dist/modules/users/index.js +10 -25
  167. package/dist/modules/users/index.js.map +1 -1
  168. package/dist/modules/users/providers/aws-user.provider.js +1 -1
  169. package/dist/modules/users/providers/aws-user.provider.js.map +1 -1
  170. package/docs/ARCHITECTURE.md +85 -29
  171. package/package.json +21 -5
  172. package/cloud-api/package-lock.json +0 -2250
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
 
6
6
  **One CLI for provider access, project infrastructure and deployments.**
7
7
 
8
- ![version](https://img.shields.io/badge/version-2.2.0-blue)
8
+ ![version](https://img.shields.io/badge/version-2.4.0-blue)
9
9
  ![node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
10
10
  ![typescript](https://img.shields.io/badge/TypeScript-5.x-blue)
11
11
  ![license](https://img.shields.io/badge/license-MIT-lightgrey)
@@ -19,7 +19,7 @@
19
19
 
20
20
  IndraQ is an internal engineering CLI that connects your team to shared infrastructure without making every developer carry organization administrator credentials.
21
21
 
22
- Instead of configuring “one AWS”, “one Jenkins”, or “one NPM” globally, v2.2 uses **provider scopes** as the only normal deployment credential path. A scope is one named account or server such as:
22
+ Instead of configuring “one AWS”, “one Jenkins”, or “one NPM” globally, IndraQ uses **provider scopes** as the normal deployment credential path. v2.3 adds a component-first project model, explicit single/multi-environment topology, and build-once immutable multi-server deployment. A scope is one named account or server such as:
23
23
 
24
24
  - `AWS — IndraQ Production`
25
25
  - `AWS — Client ABC`
@@ -55,7 +55,7 @@ flowchart LR
55
55
 
56
56
  Teams often manage several servers, customers and cloud accounts at once. A single provider credential creates ambiguity and unnecessary privilege. Scopes solve both problems.
57
57
 
58
- | Problem | v2.2 behavior |
58
+ | Problem | IndraQ behavior |
59
59
  |---|---|
60
60
  | Several AWS accounts | Unlimited named AWS scopes |
61
61
  | Several Jenkins servers | Unlimited named DEV/PROD Jenkins scopes |
@@ -85,6 +85,33 @@ A relationship between a person and a scope:
85
85
 
86
86
  A durable application definition. Deleting a developer does **not** delete the project, Jenkins jobs, DNS, proxy configuration or image associations.
87
87
 
88
+ ### Components (v2.3)
89
+
90
+ A project can contain one or many independently deployable components. Existing `frontend`, `backend`, and `frontend + backend` projects remain compatible. v2.3 also supports **User Frontend + Admin Frontend + Backend** and a custom component model underneath.
91
+
92
+ ```text
93
+ health-app
94
+ ├── backend → health-app-backend image / pipeline
95
+ ├── frontend → health-app-user image / pipeline
96
+ └── admin → health-app-admin image / pipeline
97
+ ```
98
+
99
+ Components answer **what gets built**. Deployment environments answer **where it runs**. These are deliberately separate concepts.
100
+
101
+ ### Deployment topology (v2.3)
102
+
103
+ A project can be restricted to one shared environment/server or several. Multi-environment topology is an explicit opt-in; single-server remains the default.
104
+
105
+ ```text
106
+ Project
107
+ ├── Components: backend, user frontend, admin frontend
108
+ └── Deployment environments
109
+ ├── prod-primary → Jenkins A / NPM A
110
+ └── prod-backup → Jenkins B / NPM B
111
+ ```
112
+
113
+ Use `indraq project environments` to change the allowed deployment servers later.
114
+
88
115
  ### Environment
89
116
 
90
117
  An IndraQ deployment/resource environment such as `dev`, `staging` or `prod`.
@@ -134,11 +161,25 @@ All membership changes require an audit reason and are written to the Cloud audi
134
161
  ```bash
135
162
  npm install -g indraq_cli
136
163
  indraq --version
164
+ # or
165
+ indraq -V
137
166
  ```
138
167
 
168
+ `-V` / `--version` uses a lightweight startup path and does not initialize AWS, Jenkins, NPM, Cloud, deployment, or mobile modules.
169
+
139
170
  Node.js 22+ is required.
140
171
 
141
- ### 2. Login
172
+ ### 2. Guided setup (recommended)
173
+
174
+ For a new machine/project, the shortest path is:
175
+
176
+ ```bash
177
+ indraq setup
178
+ ```
179
+
180
+ The wizard signs in if needed, registers the current folder, can create the first shared environment (admin), asks whether the project uses one or multiple servers, and can reconcile required GHCR/Jenkins infrastructure. Optional Route53/NPM setup remains optional.
181
+
182
+ Or run the individual commands manually:
142
183
 
143
184
  ```bash
144
185
  indraq login
@@ -243,9 +284,9 @@ indraq deploy --env indraq-test-airtel --select-scopes
243
284
 
244
285
  ## Provider scopes
245
286
 
246
- ### Scope selection is always visible
287
+ ### Smart scope selection
247
288
 
248
- When linking a project to a provider scope, the CLI prints the eligible scopes and asks you to choose one even when only one scope is available. This prevents silent account selection and lets you verify company/account/endpoint before linking.
289
+ When exactly one eligible provider scope is available, IndraQ can use/link that unambiguous scope without forcing an extra selection screen. When multiple eligible scopes exist, the CLI asks you to choose and shows safe company/account/endpoint metadata. Explicit `project scopes` commands remain available whenever you want to review or change a binding.
249
290
 
250
291
  ### Unlimited named scopes
251
292
 
@@ -360,10 +401,69 @@ indraq project scopes --env prod
360
401
 
361
402
  **Jenkins and GHCR are required** for deployment. AWS and NPM scope links are optional because not every project needs IndraQ-managed DNS or reverse proxy.
362
403
 
404
+ ### Configure where a project may deploy
405
+
406
+ ```bash
407
+ indraq project environments
408
+ ```
409
+
410
+ Choose one environment for a normal project, or two or more for primary/backup/replicated deployments. The first selected target is stored as `primary`, the second as `secondary`, and additional targets as `replica`. These roles describe topology; Route53 routing policy is still configured per DNS resource.
411
+
412
+ Each environment keeps its own provider-scope links, so `prod-primary` may use Jenkins/NPM instance A while `prod-backup` uses Jenkins/NPM instance B. The logical component pipeline/image name remains the same across those servers.
413
+
363
414
  ---
364
415
 
365
416
  ## Prebuild and deploy
366
417
 
418
+
419
+ ### Shared environment addressing
420
+
421
+ Each shared environment stores **two IPv4 addresses**:
422
+
423
+ - **External/Public IPv4** — used for AWS Route53/DNS A records.
424
+ - **Internal/Private IPv4** — used by Nginx Proxy Manager as the upstream server address.
425
+
426
+ Create or update environments with:
427
+
428
+ ```bash
429
+ indraq environment create
430
+ indraq environment update <name>
431
+ indraq environment list
432
+ ```
433
+
434
+ Existing environments migrated from v2.2.4 initially use the old IPv4 for both fields. Update them once if the NPM/private address is different from the public address.
435
+
436
+ ### Multi-environment deployment (v2.3)
437
+
438
+ `indraq deploy` asks **what** should be deployed and **where** it should run.
439
+
440
+ ```bash
441
+ indraq deploy
442
+ # choose backend / user frontend / admin frontend / all components
443
+ # choose prod-primary / prod-backup / ALL configured environments
444
+
445
+ indraq deploy --env prod-primary
446
+ indraq deploy --all
447
+ ```
448
+
449
+ For `--all`, IndraQ builds each selected component **once**, pushes it **once**, resolves the immutable GHCR digest, and then triggers each selected environment's Jenkins pipeline sequentially with the **same tag + digest**. Multi-environment deployment refuses to continue if environments point at different GHCR images or if the immutable digest cannot be resolved.
450
+
451
+ ```text
452
+ source
453
+ ↓
454
+ build once
455
+ ↓
456
+ GHCR tag + sha256 digest
457
+ ├── Jenkins / prod-primary
458
+ └── Jenkins / prod-backup
459
+ ```
460
+
461
+ If one Jenkins target fails, the rollout stops at that target instead of silently continuing. Reconcile required pipelines on every configured target with:
462
+
463
+ ```bash
464
+ indraq prebuild --all-targets --required-only
465
+ ```
466
+
367
467
  `prebuild` reconciles the project before deployment. It uses an admin-defined shared environment and saved project scope bindings; it does not offer a project-local custom IPv4 fallback.
368
468
 
369
469
  ```mermaid
@@ -505,11 +605,14 @@ Provider identities are removed first. Cloud identity is deleted last. Projects
505
605
 
506
606
  ### Built-in focused help
507
607
 
508
- The CLI help is aligned with the v2.2 scope-first workflow:
608
+ The CLI help is aligned with the v2.3 component/topology workflow:
509
609
 
510
610
  ```bash
611
+ indraq help setup
612
+ indraq help project
511
613
  indraq help scope
512
614
  indraq help users
615
+ indraq help environment
513
616
  indraq help deploy
514
617
  indraq help configure
515
618
  indraq help aws
@@ -563,6 +666,7 @@ indraq help aws
563
666
  | `indraq project list` | List accessible projects |
564
667
  | `indraq project link` | Link current folder |
565
668
  | `indraq project status` | Show project resources |
669
+ | `indraq project environments` | Choose one or multiple allowed deployment environments/servers |
566
670
  | `indraq project scopes --env <env>` | Select project provider scopes |
567
671
  | `indraq project add user` | Add project member + synchronize access |
568
672
  | `indraq project delete user` | Remove project member |
@@ -577,9 +681,11 @@ indraq help aws
577
681
 
578
682
  | Command | Use |
579
683
  |---|---|
580
- | `indraq prebuild --env <env>` | Reconcile infrastructure |
581
- | `indraq deploy` | Interactively choose an available shared environment and deploy |
582
- | `indraq deploy --env <env>` | Deploy an exact shared environment using its saved scope bindings |
684
+ | `indraq prebuild --env <env>` | Reconcile infrastructure for one environment |
685
+ | `indraq prebuild --all-targets --required-only` | Reconcile required GHCR/Jenkins pipelines on every configured target |
686
+ | `indraq deploy` | Choose component(s) and one/all configured project environments |
687
+ | `indraq deploy --env <env>` | Deploy one configured project environment using its saved scope bindings |
688
+ | `indraq deploy --all` | Build once per component and deploy the same immutable digest to every configured environment |
583
689
  | `indraq deploy:dev` | Convenience alias if `dev`/`development` exists; otherwise opens the environment picker |
584
690
  | `indraq deploy:prod` | Convenience alias if `prod`/`production` exists; otherwise opens the environment picker |
585
691
  | `indraq deploy --env <env> --select-scopes` | Explicitly review/change project scope bindings before deploy |
@@ -610,6 +716,36 @@ indraq proxy create api.example.com
610
716
 
611
717
  ---
612
718
 
719
+
720
+ ### Mobile apps and self-hosted OTA
721
+
722
+ IndraQ mobile projects support **Expo** and **React Native CLI**. During `indraq init`, choose **Mobile App** and then the project type. Admins create reusable mobile environments that define a build type, Jenkins DEV/PROD stage and OTA channel; developers select one during prebuild/build.
723
+
724
+ ```bash
725
+ indraq mobile environment list
726
+ indraq mobile environment create # ADMIN
727
+ indraq prebuild --env production
728
+ indraq build mobile:prod
729
+ ```
730
+
731
+ Mobile prebuild is intentionally isolated from the web infrastructure workflow: it reconciles **Jenkins + OTA only** and does not configure Docker, GHCR, AWS, Route53 or Nginx Proxy Manager.
732
+
733
+ The OTA service is hosted by the existing Cloud API at **https://cli.indraq.com** and stores immutable JS bundles/assets in **MinIO**. Expo and React Native CLI projects use `expo-updates` against this custom IndraQ server. The generated client checks only during **cold app startup** while the splash screen is held; when an eligible update is downloaded, the app force-reloads before the user enters the normal application flow.
734
+
735
+ ```bash
736
+ indraq mobile "My App" send update
737
+ indraq mobile "My App" release update
738
+ indraq mobile "My App" pause
739
+ indraq mobile "My App" rollback
740
+ indraq mobile "My App" metrics
741
+ ```
742
+
743
+ `send update` exports one immutable release and can target a specific installation ID, user ID, username, email or phone, a percentage rollout, or everyone. A tested release can then be promoted with `release update` **without rebuilding**, so production receives the exact bundle/assets that were tested.
744
+
745
+ Every successful native Jenkins build records a native compatibility fingerprint in IndraQ Cloud. If native dependencies or native Android/iOS configuration change, OTA publication is blocked until a new compatible native binary succeeds. This keeps OTA limited to JavaScript/assets that the installed binary can safely execute.
746
+
747
+ OTA release telemetry records installations, manifest delivery, downloads, successful launches, failures and rollback events. Signing private keys stay encrypted in the Cloud backend; the mobile repository receives only the public signing certificate.
748
+
613
749
  ### Persistent login sessions
614
750
 
615
751
  `indraq login` creates a persistent CLI session. The access token is refreshed automatically by the CLI, so normal users do **not** need to log in again every few hours or before each build/deployment. The session continues until `indraq logout` is run, the Cloud account is removed/disabled, or the Cloud password is reset. `indraq logout` revokes the server-side session and removes the local session credentials.
@@ -678,7 +814,7 @@ Key rules:
678
814
 
679
815
  ### `fetch failed` while configuring NPM
680
816
 
681
- v2.2 surfaces the underlying network/TLS/authentication error where possible. Verify the URL uses the correct scheme and hostname, then compare with the web login. A browser login does not necessarily prove Node.js trusts the same TLS certificate chain.
817
+ IndraQ surfaces the underlying network/TLS/authentication error where possible. Verify the URL uses the correct scheme and hostname, then compare with the web login. A browser login does not necessarily prove Node.js trusts the same TLS certificate chain.
682
818
 
683
819
  ### Jenkins says Role Strategy is not active
684
820
 
@@ -706,22 +842,19 @@ Run prebuild and choose **Skip** for Route53.
706
842
 
707
843
  ---
708
844
 
709
- ## Cloud API upgrade for v2.2
710
-
711
- The CLI and Cloud API must be upgraded together.
845
+ ## Cloud API upgrade for v2.3
712
846
 
713
- Apply migrations through:
847
+ The CLI and Cloud API should be upgraded together. Apply all SQL migrations in order through `011_environment_internal_ipv4.sql`. v2.3 itself stores project component/deployment topology inside the existing `projects.config` JSONB document, so **v2.3 does not add a new SQL migration**.
714
848
 
715
849
  ```text
716
- cloud-api/sql/001_*.sql
850
+ cloud-api/sql/001_init.sql
717
851
  ...
718
- cloud-api/sql/008_provider_scopes.sql
719
852
  cloud-api/sql/009_scope_user_secrets_and_project_lifecycle.sql
853
+ cloud-api/sql/010_persistent_auth_sessions.sql
854
+ cloud-api/sql/011_environment_internal_ipv4.sql
720
855
  ```
721
856
 
722
- Migration `009` adds encrypted per-user NPM/Jenkins secrets and project archive metadata (`archived_at`, `archived_by`). v2.2 also hardens project/resource authorization and prevents normal `USE` members from resolving shared provider-management credentials.
723
-
724
- See [UPGRADE_v2.1_to_v2.2.md](UPGRADE_v2.1_to_v2.2.md) and [RELEASE_CHECKS_v2.2.0.md](RELEASE_CHECKS_v2.2.0.md).
857
+ Migration `010` provides persistent CLI sessions. Migration `011` separates external/public environment IPv4 (Route53) from internal/private IPv4 (NPM).
725
858
 
726
859
  ---
727
860
 
@@ -739,6 +872,10 @@ Cloud API:
739
872
  ```bash
740
873
  npm --prefix cloud-api install
741
874
  npm --prefix cloud-api run build
875
+
876
+ # Cloud API development (`npm run dev`) also requires the nested install first:
877
+ # npm --prefix cloud-api install
878
+ # npm --prefix cloud-api run dev
742
879
  ```
743
880
 
744
881
  ---
@@ -746,7 +883,7 @@ npm --prefix cloud-api run build
746
883
  <div align="center">
747
884
  <img src="docs/assets/indraq-mark.png" alt="IndraQ mark" width="70" />
748
885
 
749
- **IndraQ CLI v2.2.4**
886
+ **IndraQ CLI v2.4.0**
750
887
 
751
888
  Scope-based infrastructure access. Durable projects. Safer deployments.
752
889
  </div>
@@ -12,3 +12,13 @@ SMTP_SECURE=false
12
12
  SMTP_USER=
13
13
  SMTP_PASS=
14
14
  SMTP_FROM=IndraQ <no-reply@example.com>
15
+
16
+ # Mobile OTA / MinIO
17
+ MINIO_ENDPOINT=127.0.0.1
18
+ MINIO_PORT=9000
19
+ MINIO_USE_SSL=false
20
+ MINIO_ACCESS_KEY=minioadmin
21
+ MINIO_SECRET_KEY=change-me
22
+ MINIO_BUCKET=indraq-ota
23
+ # Public Cloud API URL embedded into mobile builds. Keep this on the same cli.indraq.com backend.
24
+ PUBLIC_API_URL=https://cli.indraq.com
@@ -1,6 +1,6 @@
1
1
  # IndraQ Cloud API
2
2
 
3
- Control plane for IndraQ CLI v2.2.2. The public CLI endpoint is `https://cli.indraq.com`.
3
+ Control plane for IndraQ CLI v2.4.0 / Cloud API v1.0.0. The public CLI and OTA endpoint is `https://cli.indraq.com`.
4
4
 
5
5
  ## Responsibilities
6
6
 
@@ -12,13 +12,17 @@ Control plane for IndraQ CLI v2.2.2. The public CLI endpoint is `https://cli.ind
12
12
  - per-project/environment scope bindings
13
13
  - scope-native AWS/NPM/Jenkins identity mappings
14
14
  - self-service AWS key rotation and password lifecycle
15
- - projects, environments and project resource grants
15
+ - projects, component metadata, deployment topology, environments and project resource grants
16
16
  - audit logging
17
+ - mobile build environments and Jenkins mobile control
18
+ - self-hosted Expo Updates compatible OTA manifests/releases/targeting/metrics
19
+ - MinIO-backed immutable OTA asset storage
17
20
 
18
21
  ## Requirements
19
22
 
20
23
  - Node.js 22+
21
24
  - PostgreSQL
25
+ - MinIO (for mobile OTA bundles/assets)
22
26
 
23
27
  ## Configure
24
28
 
@@ -36,6 +40,13 @@ JWT_SECRET=replace-with-at-least-32-random-characters
36
40
  MASTER_KEY=replace-with-exactly-64-hex-characters
37
41
  BOOTSTRAP_ADMIN_EMAIL=admin@example.com
38
42
  BOOTSTRAP_ADMIN_PASSWORD=use-a-strong-password
43
+ PUBLIC_API_URL=https://cli.indraq.com
44
+ MINIO_ENDPOINT=minio.example.internal
45
+ MINIO_PORT=9000
46
+ MINIO_USE_SSL=false
47
+ MINIO_ACCESS_KEY=change-me
48
+ MINIO_SECRET_KEY=change-me
49
+ MINIO_BUCKET=indraq-ota
39
50
  ```
40
51
 
41
52
  `MASTER_KEY` must remain stable because provider scope secrets use AES-256-GCM encryption.
@@ -47,20 +58,36 @@ npm run build
47
58
  npm start
48
59
  ```
49
60
 
50
- Development:
61
+ Development (first run in the `cloud-api` directory):
51
62
 
52
63
  ```bash
64
+ npm install
53
65
  npm run dev
54
66
  ```
55
67
 
68
+ `tsx` is a Cloud API devDependency, so `npm run dev` will not work in a freshly extracted source tree until `cloud-api/node_modules` has been installed. A root-level `npm install` does not install this nested package's dependencies.
69
+
56
70
  Numbered migrations in `sql/` are applied automatically at startup. Current scope/session migrations include:
57
71
 
58
72
  ```text
59
73
  008_provider_scopes.sql
60
74
  009_scope_user_secrets_and_project_lifecycle.sql
61
75
  010_persistent_auth_sessions.sql
76
+ 011_environment_internal_ipv4.sql
77
+ 012_mobile_ota.sql
62
78
  ```
63
79
 
80
+ v2.3 deployment topology does not require a new table: it is stored inside the existing `projects.config` JSONB document and validated through `PUT /projects/:id/deployment-topology`. Each target stores environment, primary/secondary/replica role, and Jenkins stage (`dev`/`prod`).
81
+
82
+
83
+ ## Mobile OTA
84
+
85
+ Mobile OTA uses the same Cloud API and public domain as the CLI. `expo-updates` clients request manifests from `https://cli.indraq.com/ota/v1/...`; immutable JS/assets are stored in MinIO using SHA-256 object keys. Release metadata, audiences, installation identities, native-build compatibility baselines and telemetry remain in PostgreSQL.
86
+
87
+ A successful Jenkins native mobile build records the authoritative native fingerprint for its Cloud mobile environment. OTA release creation is rejected if the publishing source fingerprint does not match that baseline. Runtime changes clear the baseline until another native build succeeds.
88
+
89
+ The v2.4.0 source distribution intentionally does not ship the old v0.9.0 `package-lock.json`, because it predates the MinIO dependency. `Dockerfile` falls back to `npm install` when no lockfile exists. Generate a fresh lockfile after `npm install` if deterministic `npm ci` deployment is desired.
90
+
64
91
  ## Authorization model
65
92
 
66
93
  - **Admin** — creates/deletes scopes, grants MANAGE/USE, creates managers/admins, changes organization roles.
@@ -84,6 +111,8 @@ Related scope tables:
84
111
 
85
112
  ## Projects
86
113
 
114
+ Projects may contain multiple deployable web components and an optional single/multi-environment deployment topology. The topology references existing shared environments; provider scopes and resources remain environment-specific.
115
+
87
116
  Projects and infrastructure are durable. Deleting a user removes scope memberships/native identity mappings and the Cloud identity but retains shared project/environment/resource definitions. Ownership is reassigned before hard deletion where required.
88
117
 
89
118
  ## Persistent CLI sessions