indraq_cli 2.7.3 → 2.8.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 (64) hide show
  1. package/README.md +1547 -0
  2. package/cloud-api/README.md +6 -0
  3. package/cloud-api/dist/index.js +322 -74
  4. package/cloud-api/package.json +1 -1
  5. package/cloud-api/sql/013_ota_tester_enrollment.sql +55 -0
  6. package/cloud-api/sql/014_mobile_native_build_history.sql +50 -0
  7. package/cloud-api/src/index.ts +250 -63
  8. package/dist/cli/help-content.d.ts.map +1 -1
  9. package/dist/cli/help-content.js +13 -3
  10. package/dist/cli/help-content.js.map +1 -1
  11. package/dist/modules/cloud/services/cloud-api.service.d.ts.map +1 -1
  12. package/dist/modules/cloud/services/cloud-api.service.js +53 -15
  13. package/dist/modules/cloud/services/cloud-api.service.js.map +1 -1
  14. package/dist/modules/cloud/services/cloud-jenkins.service.d.ts +6 -1
  15. package/dist/modules/cloud/services/cloud-jenkins.service.d.ts.map +1 -1
  16. package/dist/modules/cloud/services/cloud-jenkins.service.js +62 -5
  17. package/dist/modules/cloud/services/cloud-jenkins.service.js.map +1 -1
  18. package/dist/modules/mobile/commands/build-mobile.command.js +3 -3
  19. package/dist/modules/mobile/commands/build-mobile.command.js.map +1 -1
  20. package/dist/modules/mobile/commands/configure-mobile.command.js +1 -1
  21. package/dist/modules/mobile/commands/configure-mobile.command.js.map +1 -1
  22. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts.map +1 -1
  23. package/dist/modules/mobile/commands/mobile-prebuild.command.js +20 -14
  24. package/dist/modules/mobile/commands/mobile-prebuild.command.js.map +1 -1
  25. package/dist/modules/mobile/commands/ota.command.d.ts.map +1 -1
  26. package/dist/modules/mobile/commands/ota.command.js +199 -64
  27. package/dist/modules/mobile/commands/ota.command.js.map +1 -1
  28. package/dist/modules/mobile/commands/testers.command.d.ts +7 -0
  29. package/dist/modules/mobile/commands/testers.command.d.ts.map +1 -0
  30. package/dist/modules/mobile/commands/testers.command.js +166 -0
  31. package/dist/modules/mobile/commands/testers.command.js.map +1 -0
  32. package/dist/modules/mobile/index.d.ts.map +1 -1
  33. package/dist/modules/mobile/index.js +24 -1
  34. package/dist/modules/mobile/index.js.map +1 -1
  35. package/dist/modules/mobile/services/mobile-cloud.service.d.ts +83 -0
  36. package/dist/modules/mobile/services/mobile-cloud.service.d.ts.map +1 -1
  37. package/dist/modules/mobile/services/mobile-cloud.service.js +19 -1
  38. package/dist/modules/mobile/services/mobile-cloud.service.js.map +1 -1
  39. package/dist/modules/mobile/services/ota-identity.service.d.ts +20 -0
  40. package/dist/modules/mobile/services/ota-identity.service.d.ts.map +1 -0
  41. package/dist/modules/mobile/services/ota-identity.service.js +169 -0
  42. package/dist/modules/mobile/services/ota-identity.service.js.map +1 -0
  43. package/dist/modules/mobile/services/ota-setup.service.d.ts +1 -0
  44. package/dist/modules/mobile/services/ota-setup.service.d.ts.map +1 -1
  45. package/dist/modules/mobile/services/ota-setup.service.js +268 -24
  46. package/dist/modules/mobile/services/ota-setup.service.js.map +1 -1
  47. package/dist/shared/process/run-npx.d.ts +7 -0
  48. package/dist/shared/process/run-npx.d.ts.map +1 -1
  49. package/dist/shared/process/run-npx.js +42 -1
  50. package/dist/shared/process/run-npx.js.map +1 -1
  51. package/package.json +17 -4
  52. package/vendor/QR-CODE-APACHE-2.0-LICENSE.txt +222 -0
  53. package/vendor/QR-CODE-MIT-LICENSE.txt +21 -0
  54. package/vendor/QR-CODE-NOTICE.txt +6 -0
  55. package/vendor/QRCode/QR8bitByte.js +22 -0
  56. package/vendor/QRCode/QRBitBuffer.js +38 -0
  57. package/vendor/QRCode/QRErrorCorrectLevel.js +7 -0
  58. package/vendor/QRCode/QRMaskPattern.js +10 -0
  59. package/vendor/QRCode/QRMath.js +44 -0
  60. package/vendor/QRCode/QRMode.js +6 -0
  61. package/vendor/QRCode/QRPolynomial.js +66 -0
  62. package/vendor/QRCode/QRRSBlock.js +298 -0
  63. package/vendor/QRCode/QRUtil.js +272 -0
  64. package/vendor/QRCode/index.js +462 -0
package/README.md ADDED
@@ -0,0 +1,1547 @@
1
+ # IndraQ CLI — developer guide (v2.8.0)
2
+
3
+ > **Mobile Jenkins safety policy:** IndraQ CLI **never creates, edits, replaces, repairs, or deletes** the shared mobile Jenkins Pipeline. Both `indraq mobile prebuild` and `indraq mobile build` check the existing manually managed `Mobile app Cli build` job **read-only**. If the job is missing, disabled, or has incorrect/missing parameters, the command stops; an administrator fixes Jenkins manually. Only an actual build request sends `POST /buildWithParameters` with the expected inputs.
4
+
5
+ <div align="center">
6
+ <img src="docs/assets/indraq-logo.png" alt="IndraQ Innovations" width="240" />
7
+
8
+ # IndraQ CLI
9
+
10
+ **One command-line workspace for creating, connecting, building, deploying, and maintaining web and mobile projects.**
11
+
12
+ `v2.8.0` · `Node.js 22+` · `Windows / macOS / Linux` · `IndraQ Cloud` · `Jenkins` · `Docker` · `Expo / React Native`
13
+ </div>
14
+
15
+ > **Start here:** This guide assumes you have never used IndraQ CLI before. No familiarity with Jenkins, AWS, Docker registries, or deployment pipelines is required for the developer quick start. Screens and command names reflect the **v2.8.0 CLI source**. This README is intentionally a fresh user manual, not a historical changelog.
16
+
17
+ ## Version-based OTA publishing (new in v2.8.0)
18
+
19
+ **Select a successfully built APK first; select the recipient group or device second.** `indraq mobile send update` shows verified IndraQ Cloud native-build records (e.g., Barakah 0.4 Jenkins #19, runtime `0.4-indraq-prod`), not the next local version (0.5) that prebuild prepared. The CLI temporarily configures the selected runtime **and the selected APK's version/versionCode metadata** while hashing native dependencies and exporting JavaScript, then restores your working project's `app.json`, `package.json`, generated OTA files, and `.indraq/mobile.json` even when export/publish fails. A fingerprint mismatch blocks publishing. Reusing the same runtime with conflicting native fingerprints is also blocked at Cloud.
20
+
21
+ Successful Jenkins builds are retained in **Cloud API v1.3.7** table `mobile_native_builds`. Migration `014_mobile_native_build_history.sql` runs automatically at Cloud startup and recovers previously recorded builds from verified `mobile.native-build.record` audit events where possible, including a successful 0.4 build whose single-slot baseline was invalidated by a later 0.5 prebuild. It cannot recover builds if their audit records were deleted. `indraq mobile prebuild` no longer destroys old native build history; the OTA manifest endpoint can serve all registered successful runtimes.
22
+
23
+ ```powershell
24
+ indraq mobile send update
25
+ # Choose successful installed version/build → Android/iOS → recipient audience
26
+ ```
27
+
28
+ **Reliable Cloud publishing:** Expo exports run asynchronously (avoiding `spawnSync` stalls). The API reports underlying network errors, retries transient network failures only for safe/idempotent operations, and generates one stable idempotency key per release attempt to avoid duplicate drafts. Exports are saved before upload in `.indraq/ota-outbox/<request-id>`; if Cloud goes offline, run `indraq mobile send update` again and select **Resume** to upload the identical immutable bundles without repeating Metro. The outbox directory contains a `.gitignore` and is cleared only after finalization succeeds. Avoid changing the assets in an outbox manually.
29
+
30
+ **Tester identity across upgrades:** Installation IDs are generated once and stored in the app's AsyncStorage; a normal in-place APK update with the same Android package/signing identity preserves that ID, enrollment and group access. The server continuously updates the recorded runtime and eligibility as each build opens. Deleting app data or uninstalling can reset the installation ID; distinct IDs with similar labels cannot be safely merged automatically. `indraq mobile testers rename` (WRITE access) changes only a display name. Device menus show the label, platform, runtime, and a short ID suffix to differentiate old and new installations; only currently compatible devices are offered for targeted delivery.
31
+
32
+ **Rollout:** Back up Cloud Postgres, deploy Cloud API v1.3.7 first (migration 014), then install CLI v2.8.0. Existing native binaries do not need a rebuild for the server/CLI publishing logic. The existing generated app bootstrap retains the same anonymous Installation ID and QR enrollment behavior. Do not edit the Jenkins Pipeline; it remains read-only to IndraQ.
33
+
34
+ ---
35
+
36
+ ## OTA activation reliability (v2.8.0)
37
+
38
+ Prebuild defaults to an anonymous, persistent per-installation ID. Optional saved-profile targeting can be enabled later with `indraq mobile identity configure`; it is not required for installation-based OTA.
39
+
40
+ IndraQ now tracks each downloaded OTA update ID in local app storage. If the downloaded update is pending activation, the generated bootstrap **does not fetch it again**. It attempts an immediate native `expo-updates` reload once, then verifies success on a later JS launch when `Updates.updateId` matches the downloaded update ID. If native reload fails, the app retains the downloaded update and reports `activation_failed` with recent Expo native logs. It does **not** repeatedly reload or redownload the same release. The server may still receive lightweight manifest checks so a newer repair release can supersede a stuck one, but the same downloaded release is not fetched again.
41
+
42
+ A native `ExpoUpdates.reload` rejection cannot be repaired solely by changing JavaScript: check the native module initialization (`UpdatesController`) if it persists. Emergency launch events are now reported as `emergency_launch`, not automatically interpreted as rollback. Verification uses `update_applied` rather than counting a download or a timer as a successful activation. The Jenkins Pipeline is never created or modified.
43
+
44
+ For a project created with an older CLI, run `indraq mobile prebuild` to regenerate the app-side bootstrap, review and commit the generated files, and distribute the updated JavaScript through a compatible OTA release or a fresh native build. The change is not retroactive to previously installed binaries.
45
+
46
+ ## Automatic device enrollment & targeting (v2.8.0)
47
+
48
+ **No login-screen imports, no app email/phone assumptions, no hand-entered installation IDs.** Every installed production app reports a persistent, anonymous Installation ID. Developers can enroll named QA devices using a short-lived, one-time QR invitation generated by IndraQ Cloud.
49
+
50
+ ```mermaid
51
+ flowchart LR
52
+ A[Project owner: one-time mobile prebuild] --> B[Expo deep-link + OTA bootstrap]
53
+ B --> C[Install production APK]
54
+ D[ANY project member with VIEW] --> E[indraq mobile testers invite]
55
+ E --> F[One-time private QR]
56
+ F --> G[Phone scans QR]
57
+ G --> H[Tap Open App]
58
+ H --> I[App redeems invitation]
59
+ C --> I
60
+ I --> J[Named tester installation]
61
+ J --> K[Optional tester group]
62
+ K --> L[Send signed OTA to group]
63
+ L --> M[Only matching installed runtime receives update]
64
+ ```
65
+
66
+ The Project's IndraQ owner runs this **once** from the source checkout; it does not edit Jenkins:
67
+
68
+ ```powershell
69
+ indraq mobile prebuild --env immortility --mode prod
70
+ indraq mobile build --env immortility --type expo --mode prod --output apk --profile fast
71
+ ```
72
+
73
+ Prebuild registers the native Expo deep-link scheme with IndraQ Cloud, generates `indraq-ota/bootstrap.js`, and creates the Expo Router `app/indraq-enroll.jsx` route **only if the route does not exist**. If the native scheme did not exist in the previously installed APK, install a new release APK first. Existing apps need the new generated bootstrap to receive QR enrollment deep links.
74
+
75
+ **Every active IndraQ user with access to that project**, including normal users with VIEW permission, can generate a QR from any directory (not necessarily a clone of the app):
76
+
77
+ ```powershell
78
+ indraq mobile testers invite
79
+ ```
80
+
81
+ The command prompts for app (if multiple are accessible), device name, optional group and validity (5/15/30/60 minutes). It displays an actual QR in the terminal and saves an SVG to `.indraq/ota-enroll-<invitation-id>.svg` locally. Give it to the tester privately. The tester scans with their phone's camera, opens the enrollment webpage, and taps **Open App**. The IndraQ-enabled app redeems it once and registers the device without needing the app's login email or phone.
82
+
83
+ ```powershell
84
+ indraq mobile testers list
85
+ indraq mobile testers installations
86
+ indraq mobile testers group create
87
+ indraq mobile testers revoke
88
+ indraq mobile testers rename
89
+ indraq mobile send update
90
+ ```
91
+
92
+ During **Send update**, pick **Tester groups**, **Named testers**, **Selected installations**, **Percentage rollout**, or **Everyone**. Group membership is checked against the live tester registry at each manifest request; revoking a tester prevents it from receiving future group-targeted releases. The Cloud API restricts release publishing to project WRITE permissions.
93
+
94
+ | Operation | Minimum project permission |
95
+ |---|---|
96
+ | Generate QR invitations and list own project's devices | **VIEW — all user roles** |
97
+ | Create QA/Beta tester groups or revoke enrollments | **WRITE** |
98
+ | Publish, promote, pause or roll back OTA releases | **WRITE** |
99
+
100
+ **Security:** The invitation is a one-time token (hashed at rest), expires in 5–60 minutes, and does not grant a Cloud user account or permission to publish. QR generation happens on the local computer using a bundled QR encoder—no outside QR service receives the invitation. Treat the SVG/link as confidential until redeemed. A tester device must already have registered its IndraQ-enabled app installation. Installation IDs are **device delivery identifiers**, not strong user authentication or verified proof of account identity.
101
+
102
+ **Platform scope:** Automated deep-link enrollment setup is currently implemented for **Expo** (including Expo Router). Existing React Native CLI projects can still receive installation-based and general OTA releases, but native QR deep links need a separate explicit Android/iOS link integration before enrollment will work. Live QR scanning, update application, and device testing must be verified before production rollout.
103
+
104
+ ---
105
+
106
+ ## Automatic OTA audience identities (v2.8.0)
107
+
108
+ The primary workflow now uses **per-installation QR enrollment** and does **not** inspect or require each application's login users. The earlier profile adapter remains optional for legacy email/phone targeting: `indraq mobile prebuild` defaults to anonymous installation identity and reuses existing `indraq-ota/identity.json`. Only a developer deliberately running `indraq mobile identity configure` is asked to select saved profile keys.
109
+
110
+ ```powershell
111
+ indraq mobile prebuild --env immortility --mode prod
112
+ indraq mobile identity status
113
+ # Only if you change where the application saves user profiles:
114
+ indraq mobile identity configure
115
+ indraq mobile prebuild --env immortility --mode prod
116
+ ```
117
+
118
+ The adapter reads only the configured profile key, extracts `userId`, `username`, `email` and `phone` from conventional JSON fields or one-time custom paths, and reports changes as `identity_synced` while the app is foregrounded. The server clears prior identity fields on sign-out. Updates remain **startup-only** and will be checked on the next cold launch; no automatic reload during login or checkout. An installation ID is always available, even without an authenticated user.
119
+
120
+ **Important limitations:** There is no safe universal way to discover a custom app's logged-in identity. If the app stores only an opaque token, uses Redux-persist double-encoded JSON, keeps auth only in memory, or uses another storage backend, select installation-only mode until you add an explicit adapter or expose a readable, persisted profile. A configured storage key must contain a *profile*, not an access token or password. For SecureStore adapters, the native app needs `expo-secure-store`; prebuild installs it if missing, and then a new native build is required. For an already-installed app, publish the new identity bootstrap as an all-user OTA update first; **only subsequent updates** can reliably target that user's email/phone.
121
+
122
+ **Security:** Email/phone/user IDs in the current OTA request are client-reported routing attributes, **not verified authorization identities**. Treat the targeted rollout as convenience filtering, not protection for confidential content. Production-grade verified targeting requires a server-verified session/auth token integration.
123
+
124
+ **Jenkins protection remains absolute:** `mobile prebuild`, `mobile identity` and `mobile build` never create, replace, or edit the Jenkins Pipeline. They only validate the existing job and submit build parameters.
125
+
126
+ ## Live provider account checks and self-hosted OTA troubleshooting (v2.8.0)
127
+
128
+ A **Cloud scope assignment does not guarantee a working provider login**. Provider accounts can be deleted or changed directly in Jenkins, NPM, or AWS after IndraQ initially provisions them.
129
+
130
+ ```powershell
131
+ indraq scope members # Read Cloud assignment + live provider account state
132
+ indraq scope sync # Inspect drift; explicitly choose accounts to repair
133
+ indraq scope add-user # Select an existing user and ANY additional scope
134
+ ```
135
+
136
+ The same IndraQ user can be granted access separately to Jenkins Immortility, Jenkins IndraQ, AWS accounts and NPM servers. Each scope has its own credentials and permissions. **No duplicate IndraQ Cloud account is needed.** `scope sync` never deletes external users or silently removes Cloud membership. It checks native-account existence and, for Jenkins/NPM, verifies stored provider credentials server-side without revealing passwords. External permission drift may still need manual review. On Jenkins, newly provisioned credentials are now login-tested before access is reported as successful. GitHub Packages scope access does **not** create a GitHub login or accept an organization invitation.
137
+
138
+ ### OTA update not received?
139
+
140
+ ```powershell
141
+ indraq mobile doctor # Inspect OTA server, releases, native baseline, installations
142
+ indraq mobile metrics # Live IndraQ OTA telemetry
143
+ indraq mobile build --env immortility --type expo --mode prod --output apk
144
+ ```
145
+
146
+ **Important:** Expo Development Client/debug builds do not run the startup-only IndraQ OTA check. Use a **release-mode APK** for a normal OTA test and ensure its OTA channel, runtime and native fingerprint match the targeted release. After the app launches online, its installation should appear in `indraq mobile metrics`.
147
+
148
+ For a release targeted to one logged-in account, your application's login code must call:
149
+
150
+ ```javascript
151
+ import { identifyIndraqOTA } from './indraq-ota/bootstrap';
152
+ await identifyIndraqOTA({ userId: account.id, email: account.email, username: account.username, phone: account.phone });
153
+ ```
154
+
155
+ Then **fully close and reopen** the installed release app. Target matching requires identity metadata from the app, not merely an existing logged-in session. IndraQ runs its own OTA server, so its releases and user counts are **not displayed in the Expo EAS Update dashboard**. Use `indraq mobile metrics` instead.
156
+
157
+ ---
158
+
159
+ ---
160
+
161
+ ## Contents
162
+
163
+ 1. [What is IndraQ CLI?](#1-what-is-indraq-cli)
164
+ 2. [Why use it, and how does it work?](#2-why-use-it-and-how-does-it-work)
165
+ 3. [Install and sign in](#3-install-and-sign-in)
166
+ 4. [Project types and folder layouts](#4-project-types-and-folder-layouts)
167
+ 5. [Quick-start recipes](#5-quick-start-recipes)
168
+ 6. [Complete command map](#6-complete-command-map)
169
+ 7. [Command explanations and examples](#7-command-explanations-and-examples)
170
+ 8. [Web deployment: from code to server](#8-web-deployment-from-code-to-server)
171
+ 9. [Mobile builds and OTA updates](#9-mobile-builds-and-ota-updates)
172
+ 10. [Environments, scopes, and permissions](#10-environments-scopes-and-permissions)
173
+ 11. [Safe project deletion](#11-safe-project-deletion)
174
+ 12. [Configuration files and secrets](#12-configuration-files-and-secrets)
175
+ 13. [Troubleshooting](#13-troubleshooting)
176
+ 14. [FAQs, glossary, and developer notes](#14-faqs-glossary-and-developer-notes)
177
+
178
+ ---
179
+
180
+ ## 1. What is IndraQ CLI?
181
+
182
+ **IndraQ CLI** is an internal command-line application maintained by **IndraQ Innovations**. It lets developers work with IndraQ's shared engineering infrastructure directly from a terminal (PowerShell, Command Prompt, Terminal, or a VS Code terminal).
183
+
184
+ Instead of manually opening multiple dashboards and repeating configuration work, you run a command such as:
185
+
186
+ ```powershell
187
+ indraq setup
188
+ ```
189
+
190
+ The CLI asks friendly questions, checks your permissions, connects to **IndraQ Cloud**, and performs the selected setup or deployment tasks.
191
+
192
+ | Without a shared CLI | With IndraQ CLI |
193
+ |---|---|
194
+ | Manually create web deployment jobs | Use the guided setup / web prebuild workflow; mobile Jenkins remains manually managed |
195
+ | Manually identify container registry packages | Create or link a GitHub container package |
196
+ | Repeat deployment configuration per server | Save a project deployment topology |
197
+ | Configure DNS and reverse proxy separately | Select Route53 and NPM tasks when needed |
198
+ | Manually package mobile source for Jenkins | Run `indraq mobile build` |
199
+ | Manually manage JavaScript update releases | Publish controlled OTA updates |
200
+ | Guess which infrastructure belongs to a project | Review associations with `indraq project status` |
201
+
202
+ **What IndraQ CLI is not:** It is not your application framework, a replacement for Git, an iOS native build service, or a tool that grants permissions you do not already have.
203
+
204
+ ## 2. Why use it, and how does it work?
205
+
206
+ ### 2.1 The platform at a glance
207
+
208
+ ![IndraQ CLI architecture](docs/assets/architecture.svg)
209
+
210
+ **Follow the arrows:** a developer uses the CLI; the CLI checks IndraQ Cloud for identity, project configuration, and access; the platform then works with the selected infrastructure providers.
211
+
212
+ | Part | Plain-English purpose |
213
+ |---|---|
214
+ | **Your application folder** | Contains the code you write |
215
+ | **IndraQ CLI** | Guides you through actions and sends authorized requests |
216
+ | **IndraQ Cloud API** | Stores your project links, scope assignments, policies, audit events, and OTA information |
217
+ | **GitHub Packages (GHCR)** | Stores Docker container images for web deployment |
218
+ | **Jenkins** | Runs server deployment pipelines and Android build jobs |
219
+ | **Route53** | Points public domains to public server IPs |
220
+ | **Nginx Proxy Manager (NPM)** | Routes HTTPS requests to internal server IPs and ports |
221
+ | **IndraQ OTA + MinIO** | Distributes compatible signed JavaScript/asset updates to mobile apps |
222
+
223
+ > **Important:** “NPM” in infrastructure menus means **Nginx Proxy Manager**, not the `npm` command used to install JavaScript packages.
224
+
225
+ ### 2.2 Typical journey
226
+
227
+ ![Getting started flow](docs/assets/setup-flow.svg)
228
+
229
+ ```mermaid
230
+ flowchart TD
231
+ A[Open your project folder] --> B{Already linked to IndraQ Cloud?}
232
+ B -- No --> C[indraq project create or indraq init]
233
+ B -- Yes --> D[indraq project status]
234
+ C --> D
235
+ D --> E{What are you working on?}
236
+ E -- Web/backend --> F[indraq prebuild]
237
+ E -- Mobile --> G[indraq mobile prebuild]
238
+ E -- Both --> H[Configure backend then mobile]
239
+ F --> I[indraq deploy]
240
+ G --> J[indraq mobile build]
241
+ H --> I
242
+ H --> J
243
+ ```
244
+
245
+ There are **two separate ideas** to remember:
246
+
247
+ - **A project component** is *what* you are building: frontend, backend, mobile app, and so on.
248
+ - **An environment** is *where/how* it is deployed or built: a web server/environment or an admin-managed mobile build environment.
249
+
250
+ During new web project creation, developers see **one setup list** to select Dockerfile(s), GitHub Packages, Jenkins, Route53, and Nginx Proxy Manager. Only selected services are configured.
251
+
252
+ ### 2.3 What happens automatically versus manually?
253
+
254
+ | Operation | You choose | The CLI handles |
255
+ |---|---|---|
256
+ | First-time setup | Project type, environment, setup tasks | Links project and reconciles selected infrastructure |
257
+ | Reuse existing services | Link existing versus create/reconcile | Validates and records the selected association |
258
+ | Web deploy | Component(s), target(s), image tag | Build, push, Jenkins execution, and log streaming |
259
+ | Android build | Build server, Expo/native, dev/staging/prod, output/profile | Source snapshot, `.env` handling, Jenkins build, artifact links |
260
+ | OTA release | Environment, audience, update | Export, signing, upload, release controls |
261
+ | Project deletion | Which associated resources to delete or keep | Authorization checks and selected cleanup |
262
+
263
+ ---
264
+
265
+ ## 3. Install and sign in
266
+
267
+ ### 3.1 Requirements
268
+
269
+ | Item | Needed for | Notes |
270
+ |---|---|---|
271
+ | **Node.js 22+** | CLI | Verify with `node -v` |
272
+ | **npm** | Install CLI | Bundled with Node.js |
273
+ | **IndraQ Cloud account** | Login | An organization admin or manager must provide access |
274
+ | **Internet/network access** | Cloud, GitHub, Jenkins, AWS, NPM | You must be able to reach the services assigned to you |
275
+ | **Project source folder** | Build or deploy | Use VS Code or any editor |
276
+ | **Docker** | Web image build | Required on the machine performing local Docker image builds |
277
+ | **Expo / React Native dependencies** | Mobile builds | CLI checks the actual mobile framework and project |
278
+ | **Access to a configured Jenkins controller** | Web/mobile builds | Admin normally sets up provider scopes and mobile environments |
279
+
280
+ ### 3.2 Install the CLI
281
+
282
+ **Windows — PowerShell** (also works in macOS/Linux terminals):
283
+
284
+ ```powershell
285
+ node -v
286
+ npm -v
287
+ npm install -g indraq_cli
288
+ indraq --version
289
+ indraq --help
290
+ ```
291
+
292
+ The npm package name is `indraq_cli`; the terminal command is **`indraq`**.
293
+
294
+ To update an installation:
295
+
296
+ ```powershell
297
+ npm install -g indraq_cli@latest
298
+ indraq --version
299
+ ```
300
+
301
+ > For development of the **CLI itself**, clone or extract its source and run `npm install`, `npm run build`, and `npm test`. Those are not required for a normal global CLI installation.
302
+
303
+ ### 3.3 Log in once
304
+
305
+ ```powershell
306
+ indraq login
307
+ indraq whoami
308
+ ```
309
+
310
+ The CLI retains a Cloud login session and refreshes it until logout or a security revocation. You do **not** need to log in before every deployment.
311
+
312
+ ```powershell
313
+ indraq logout
314
+ ```
315
+
316
+ This revokes your persistent session and clears the local session credentials.
317
+
318
+ ### 3.4 First command to learn
319
+
320
+ ```powershell
321
+ indraq setup
322
+ ```
323
+
324
+ `setup` is the guided repair/onboarding flow for a project. If you already have application code, open its folder first and let the wizard register or link it.
325
+
326
+ ---
327
+
328
+ ## 4. Project types and folder layouts
329
+
330
+ The CLI supports the following presets:
331
+
332
+ | Project type | Cloud kind | Typical structure | Deployment path |
333
+ |---|---|---|---|
334
+ | Frontend | `frontend` | `./` | Web image → Jenkins |
335
+ | Backend | `backend` | `./` | Web image → Jenkins |
336
+ | Frontend + Backend | `fullstack` | `frontend/`, `backend/` | Each component → web pipeline |
337
+ | User Frontend + Admin Frontend + Backend | `multiweb` | `frontend/`, `admin/`, `backend/` | Three web components |
338
+ | Mobile App | `mobile` | `./` or designated app folder | Android Jenkins + OTA |
339
+ | **Backend + Mobile App** | `backend-mobile` | `backend/`, `mobile/` | Backend web pipeline + mobile Jenkins/OTA |
340
+
341
+ ### 4.1 Visual folder layouts
342
+
343
+ ```text
344
+ WEB APP BACKEND + MOBILE APP
345
+ my-web-project/ my-combined-project/
346
+ ├── frontend/ ├── backend/
347
+ ├── backend/ │ ├── package.json
348
+ └── .indraq/ │ └── Dockerfile
349
+ ├── mobile/
350
+ │ ├── package.json
351
+ │ └── app.json
352
+ └── .indraq/
353
+ ```
354
+
355
+ Paths above are examples. Single-component projects may use the root folder directly. Existing application files are preserved during `indraq project create`.
356
+
357
+ ### 4.2 One project, two different build paths
358
+
359
+ ![Backend + Mobile App project](docs/assets/backend-mobile.svg)
360
+
361
+ For `backend-mobile`, the backend uses container infrastructure, while mobile uses its separate Android/OTA workflow. Both share the **same Cloud project association**. From `backend/`, web prebuild is used; from `mobile/`, mobile prebuild is used. At the project root, guided setup can configure both.
362
+
363
+ ### 4.3 When to use `init`, `project create`, or `project link`
364
+
365
+ ```mermaid
366
+ flowchart TD
367
+ Start{What do you have?}
368
+ Start -- No source code yet --> Init[indraq init]
369
+ Start -- Existing local source, new Cloud project --> Create[indraq project create]
370
+ Start -- Existing Cloud project, new computer/folder --> Link[indraq project link]
371
+ Start -- Unsure or repairing setup --> Setup[indraq setup]
372
+ ```
373
+
374
+ | Command | Does it generate app source? | Best use |
375
+ |---|---|---|
376
+ | `indraq init` | **Yes**, on a new project | Start a new application from a supported template/generator |
377
+ | `indraq project create` | **No**; keeps your code | Register existing source and optionally configure infrastructure |
378
+ | `indraq project link` | No | Connect a folder to an accessible existing Cloud project |
379
+ | `indraq setup` | Uses existing state and prompts | Guided create/link/setup/repair |
380
+
381
+ **Safety:** `init` warns and requires a deliberate double confirmation before overwriting a populated folder that has not already been initialized by IndraQ.
382
+
383
+ ---
384
+
385
+ ## 5. Quick-start recipes
386
+
387
+ These are the shortest routes to a working project. Copy the example commands, replacing the paths/environment names with yours.
388
+
389
+ ### Recipe A — Existing web or backend project
390
+
391
+ ```powershell
392
+ cd C:\Projects\my-backend
393
+ indraq login
394
+ indraq project create
395
+ indraq prebuild
396
+ indraq project status
397
+ indraq deploy
398
+ ```
399
+
400
+ During project creation you can choose an environment and one setup checklist:
401
+
402
+ ```text
403
+ What do you want to configure now?
404
+ [x] Dockerfile(s)
405
+ [x] GitHub Packages
406
+ [x] Jenkins
407
+ [ ] AWS Route53
408
+ [ ] Nginx Proxy Manager
409
+ ```
410
+
411
+ Select only what you need. You can always run `indraq prebuild` later to add optional infrastructure.
412
+
413
+ ### Recipe B — New project from scratch
414
+
415
+ ```powershell
416
+ mkdir C:\Projects\my-new-app
417
+ cd C:\Projects\my-new-app
418
+ indraq init
419
+ ```
420
+
421
+ Choose a project type and answer the generator prompts. The CLI then links the project to Cloud and offers the relevant infrastructure setup. You can skip dependency installation with `indraq init --skip-install` if desired.
422
+
423
+ ### Recipe C — Existing Expo or React Native app
424
+
425
+ ```powershell
426
+ cd C:\Projects\my-mobile-app
427
+ indraq project create
428
+ indraq mobile environment list
429
+ indraq mobile build --dry-run
430
+ indraq mobile build
431
+ ```
432
+
433
+ The guided build first asks which mobile/Jenkins environment to use, then the framework (Expo or React Native CLI), build type (Development, Staging, Production), output, and profile. **Any active mobile environment can run any Android build type** if its Jenkins server is properly configured.
434
+
435
+ **What your first Android build produces** depends on the framework and environment. For Expo Development it produces a **Development Client APK**. It does not produce a store-ready release APK.
436
+
437
+ ### Recipe D — Backend + Mobile App
438
+
439
+ ```powershell
440
+ cd C:\Projects\my-combined-project
441
+ indraq project create
442
+ ```
443
+
444
+ Select **Backend + Mobile App** and the backend/mobile directories. The CLI can configure the backend first and then prompt to configure mobile Jenkins + OTA, within the same project creation/setup flow.
445
+
446
+ Later, work from either subfolder:
447
+
448
+ ```powershell
449
+ cd C:\Projects\my-combined-project\backend
450
+ indraq prebuild
451
+ indraq deploy
452
+
453
+ cd C:\Projects\my-combined-project\mobile
454
+ indraq prebuild --env <mobile-environment-slug>
455
+ indraq mobile build
456
+ ```
457
+
458
+ ### Recipe E — Deploy the same web image to multiple servers
459
+
460
+ ```powershell
461
+ indraq project environments
462
+ indraq prebuild --all-targets
463
+ indraq deploy --all
464
+ ```
465
+
466
+ The same immutable image digest is deployed to all selected targets (provided they share the correct logical GitHub Packages image). This is not a separate rebuild per server.
467
+
468
+ ### Recipe F — Make an OTA update after a successful native build
469
+
470
+ ```powershell
471
+ indraq mobile send update --app "My App" --env <mobile-environment-slug>
472
+ indraq mobile metrics --app "My App"
473
+ ```
474
+
475
+ Test the update with a limited audience before running:
476
+
477
+ ```powershell
478
+ indraq mobile release update --app "My App"
479
+ ```
480
+
481
+ OTA is for compatible JavaScript and asset changes, **not** changes requiring a new native binary.
482
+
483
+ ---
484
+
485
+ ## 6. Complete command map
486
+
487
+ The command list below is based on the **actual v2.7.9 command registration**, including normal commands, administrative commands, and compatibility aliases.
488
+
489
+ ### 6.1 Navigation map
490
+
491
+ ```mermaid
492
+ mindmap
493
+ root((indraq))
494
+ Start
495
+ help
496
+ doctor
497
+ login/logout
498
+ setup
499
+ configure
500
+ Projects
501
+ init
502
+ project
503
+ access
504
+ Web
505
+ prebuild
506
+ deploy
507
+ deployment
508
+ dockerfile
509
+ Mobile
510
+ mobile environment
511
+ mobile prebuild
512
+ build mobile:dev/staging/prod
513
+ mobile OTA
514
+ Infrastructure
515
+ scope
516
+ environment
517
+ jenkins
518
+ dns
519
+ proxy
520
+ iam
521
+ healthcheck
522
+ Organization
523
+ user
524
+ password
525
+ logs
526
+ ```
527
+
528
+ ### 6.2 Start, help, authentication, and configuration
529
+
530
+ | Command | What it does |
531
+ |---|---|
532
+ | `indraq --help` | Show CLI overview and full command reference |
533
+ | `indraq --version` / `indraq -V` | Show installed CLI version |
534
+ | `indraq help [topic]` | Show focused help; topics include `project`, `mobile`, `scope`, `aws`, and more |
535
+ | `indraq doctor` | Diagnose Node.js, npm and CLI command-resolution problems |
536
+ | `indraq login` | Sign in to IndraQ Cloud |
537
+ | `indraq logout` | Revoke and clear the local persistent session |
538
+ | `indraq whoami` | Show the authenticated Cloud identity |
539
+ | `indraq password reset` | Recover/reset Cloud or supported provider passwords using email OTP |
540
+ | `indraq setup` | Guided project onboarding and infrastructure repair |
541
+ | `indraq configure` | Open configuration home: scopes, project infrastructure, mobile settings |
542
+
543
+ ### 6.3 Projects and membership
544
+
545
+ | Command | What it does |
546
+ |---|---|
547
+ | `indraq init [directory]` | Scaffold a new web/mobile project and link Cloud project |
548
+ | `indraq project create [name]` | Register current source as a Cloud project; optional setup |
549
+ | `indraq project list` | List projects visible to you |
550
+ | `indraq project link` | Associate current folder with an existing Cloud project |
551
+ | `indraq project sync` | Migrate old local project metadata to a Cloud project reference |
552
+ | `indraq project status` | Display components, environments and resource associations |
553
+ | `indraq project environments` | Choose deployment targets for a project |
554
+ | `indraq project targets` | Alias for `project environments` |
555
+ | `indraq project scopes --env <name>` | Choose provider scopes for the specified environment |
556
+ | `indraq project add user` | Add a user to a project |
557
+ | `indraq project delete user` | Remove a user from a project |
558
+ | `indraq project rename [name]` | Rename a project |
559
+ | `indraq project archive` | Archive a project to block deployment mutations |
560
+ | `indraq project restore` | Restore an archived project |
561
+ | `indraq project delete` | Delete Cloud project and optionally selected associated external resources |
562
+ | `indraq access add user` | Grant access to selected AWS/NPM/Jenkins project resources |
563
+ | `indraq access delete user` | Revoke access to selected project resources |
564
+
565
+ ### 6.4 Web setup and deployment
566
+
567
+ | Command | What it does |
568
+ |---|---|
569
+ | `indraq dockerfile create` | Generate missing Docker artifacts for an existing application |
570
+ | `indraq prebuild` | Select and configure permitted infrastructure (mobile Jenkins is read-only) |
571
+ | `indraq prebuild --env <name>` | Prebuild a specific deployment environment (or mobile environment in mobile context) |
572
+ | `indraq prebuild --all-targets` | Configure all project web deployment targets |
573
+ | `indraq prebuild --required-only` | Only GitHub Packages and Jenkins for a web project |
574
+ | `indraq deploy` | Build, push, and deploy chosen web component(s) |
575
+ | `indraq deploy --env <name>` | Deploy one selected environment |
576
+ | `indraq deploy --all` | Deploy the same image digest to all configured targets |
577
+ | `indraq deploy --select-scopes` | Review/change provider scope bindings as part of deployment |
578
+ | `indraq deploy build` | Compatibility subcommand for build/push/deploy |
579
+ | `indraq deploy configure` | Open main configuration menu |
580
+ | `indraq deployment create` | Reconcile deployment infrastructure (prebuild alias) |
581
+ | `indraq deployment run` | Run a web deployment |
582
+ | `indraq deploy:configure` | Alias for `indraq configure` |
583
+ | `indraq deploy:dev` | Target an environment named dev/development, if configured |
584
+ | `indraq deploy:prod` | Target an environment named prod/production, if configured |
585
+
586
+ ### 6.5 Mobile environments, Android build, and OTA
587
+
588
+ | Command | What it does |
589
+ |---|---|
590
+ | `indraq mobile environment list` | Show active mobile environments |
591
+ | `indraq mobile environment create` | Create admin-managed mobile environment |
592
+ | `indraq mobile environment update` | Update a mobile environment |
593
+ | `indraq mobile environment delete` | Disable a mobile environment |
594
+ | `indraq mobile env ...` | Alias for `indraq mobile environment ...` |
595
+ | `indraq mobile prebuild --env <name> --mode <dev|staging|prod>` | Validate existing mobile Jenkins pipeline (read-only) and configure OTA runtime |
596
+ | **`indraq mobile build`** | **Guided build: choose Jenkins environment first, Expo/React Native, Development/Staging/Production, output and profile** |
597
+ | `indraq mobile build --env immortility --mode prod --type expo --output aab --profile clean` | Run with explicit selections instead of prompts (still confirms before build) |
598
+ | `indraq build mobile:dev` | Android Development build |
599
+ | `indraq build mobile:development` | Alias for development build |
600
+ | `indraq build mobile:staging` | Android Staging build |
601
+ | `indraq build mobile:prod` | Android Production build |
602
+ | `indraq build mobile:production` | Alias for production build |
603
+ | `indraq mobile testers invite` | All project users with VIEW access can generate one-time QR invites (any directory) |
604
+ | `indraq mobile testers list` | Show testers and groups |
605
+ | `indraq mobile testers installations` | Show installations registered with OTA |
606
+ | `indraq mobile testers group create` | Create a named tester group (WRITE) |
607
+ | `indraq mobile testers revoke` | Revoke enrolled tester access (WRITE) |
608
+ | `indraq mobile testers rename` | Rename an enrolled device without new QR (WRITE) |
609
+ | `indraq mobile send update` | Export an OTA update; select groups, named testers, installations, percentage or everyone |
610
+ | `indraq mobile release update` | Promote a tested immutable OTA release to everyone |
611
+ | `indraq mobile pause` | Pause a selected OTA release |
612
+ | `indraq mobile rollback` | Republish previous known-good OTA assets |
613
+ | `indraq mobile metrics` | Show OTA release statistics and adoption |
614
+ | `indraq mobile doctor` | Diagnose update server health, OTA compatibility, registered installations and release targeting |
615
+
616
+ **Preferred:** `indraq mobile build`. Legacy shortcuts such as `indraq build mobile:prod` remain supported. `indraq mobile build:prod` is **not** a command; use `indraq mobile build --mode prod`.
617
+
618
+ ### 6.6 Organization environments and provider scopes
619
+
620
+ | Command | What it does |
621
+ |---|---|
622
+ | `indraq environment create` | Create a shared web environment with public/private IPs (admin) |
623
+ | `indraq environment list` | List shared web environments |
624
+ | `indraq environment update [name]` | Update an environment (admin) |
625
+ | `indraq environment delete [name]` | Delete unused environment (admin) |
626
+ | `indraq scope list` | List only provider scopes assigned to you |
627
+ | `indraq scope describe [nameOrId]` | Inspect scope metadata without exposing secrets |
628
+ | `indraq scope create [provider]` | Create scope for AWS/NPM/Jenkins/GitHub Packages (admin) |
629
+ | `indraq scope aws-zone [nameOrId]` | Set AWS scope default hosted zone (admin) |
630
+ | `indraq scope delete [nameOrId]` | Delete unused provider scope (admin) |
631
+ | `indraq scope members` | List Cloud members and verify live Jenkins/NPM/AWS identities and login status |
632
+ | `indraq scope sync` | Inspect missing/stale provider users, and optionally repair identities or credentials |
633
+ | `indraq scope add-user` | Add scope membership and native identity |
634
+ | `indraq scope remove-user` | Remove scope membership and associated native identity |
635
+ | `indraq scope default [provider]` | Set your personal default scope for a provider |
636
+ | `indraq scope audit` | Review scope change history |
637
+ | `indraq scope credentials` | Display your own managed AWS CLI credential |
638
+ | `indraq scope rotate-key` | Rotate your own AWS access key |
639
+ | `indraq scope rotate-password` | Rotate your NPM/Jenkins password |
640
+
641
+ ### 6.7 Organization users and audit
642
+
643
+ | Command | What it does |
644
+ |---|---|
645
+ | `indraq user list` | List Cloud users (manager/admin) |
646
+ | `indraq user scopes [email]` | List your own or manageable user's scopes |
647
+ | `indraq user create [username]` | Create Cloud user and assign selected scopes |
648
+ | `indraq user update [username]` | Update user profile/role within permissions |
649
+ | `indraq user delete [username]` | Clean up manageable native identities and delete Cloud user |
650
+ | `indraq logs` | View organization audit logs (manager/admin) |
651
+
652
+ ### 6.8 Jenkins administration and direct builds
653
+
654
+ | Command | What it does |
655
+ |---|---|
656
+ | `indraq jenkins pipelines` | List visible runnable Jenkins jobs |
657
+ | `indraq jenkins build [job]` | Run selected pipeline; prompt for its parameters; stream logs |
658
+ | `indraq jenkins run [job]` | Alias for `jenkins build` |
659
+ | `indraq jenkins pipeline:run [job]` | Compatibility alias |
660
+ | `indraq jenkins deployments` | List Jenkins deployment jobs |
661
+ | `indraq jenkins create-deployment` | Start bootstrap CREATE-DEPLOYMENT pipeline |
662
+ | `indraq jenkins deployment:update [job]` | Reconcile/update a Jenkins deployment job |
663
+ | `indraq jenkins deployment:delete [job]` | Delete a selected Jenkins deployment job |
664
+ | `indraq jenkins users` | List Jenkins users |
665
+ | `indraq jenkins user:update [username]` | Update a Jenkins user |
666
+ | `indraq jenkins user:delete [username]` | Delete a Jenkins user |
667
+
668
+ ### 6.9 AWS, Route53, health checks and proxy administration
669
+
670
+ | Command | What it does |
671
+ |---|---|
672
+ | `indraq iam users` | List AWS IAM users |
673
+ | `indraq iam user:create [username]` | Create IAM CLI user/access key |
674
+ | `indraq iam user:update [username]` | Update IAM managed policies |
675
+ | `indraq iam user:delete [username]` | Delete IAM identity and supported dependencies |
676
+ | `indraq iam credentials [username]` | Show authorized stored AWS IAM credentials |
677
+ | `indraq iam access-key rotate [username]` | Rotate managed AWS access key |
678
+ | `indraq dns zones` | List Route53 hosted zones |
679
+ | `indraq dns records --zone <id>` | List record sets in a zone |
680
+ | `indraq dns create [record]` | Create Route53 A record |
681
+ | `indraq dns update [record]` | Create/update A record via UPSERT |
682
+ | `indraq dns delete [record]` | Delete selected Route53 record set(s) |
683
+ | `indraq healthcheck list` | List Route53 health checks |
684
+ | `indraq healthcheck create` | Create health check (admin) |
685
+ | `indraq healthcheck delete [id]` | Delete health check (admin) |
686
+ | `indraq proxy list` | List Nginx Proxy Manager proxy hosts |
687
+ | `indraq proxy create [domain]` | Create proxy host |
688
+ | `indraq proxy update [domain]` | Update proxy host |
689
+ | `indraq proxy delete [domain]` | Delete proxy host |
690
+ | `indraq npm-user list` | List NPM users |
691
+ | `indraq npm-user create` | Create NPM user |
692
+ | `indraq npm-user update [identity]` | Update NPM user |
693
+ | `indraq npm-user delete [identity]` | Delete NPM user |
694
+
695
+ ### 6.10 Compatibility / legacy aliases
696
+
697
+ These commands remain registered for older workflows. **New users should prefer the commands already listed above.**
698
+
699
+ | Legacy command | Use instead |
700
+ |---|---|
701
+ | `indraq cloud login`, `cloud logout`, `cloud whoami` | `indraq login`, `logout`, `whoami` |
702
+ | `indraq server create`, `indraq server list` | `indraq environment create/list` |
703
+ | `indraq provider configure`, `provider list`, `provider describe`, `provider default` | `indraq scope ...` |
704
+ | `indraq credentials configure`, `credentials list`, `credentials sync`, `credentials restore` | Manage scopes and credentials using supported scope flows |
705
+
706
+ ---
707
+
708
+ ## 7. Command explanations and examples
709
+
710
+ The earlier command map answers **“which command exists?”** This chapter answers **“when and how should I use it?”**
711
+
712
+ ### 7.1 `login`, `logout`, `whoami`, `password reset`
713
+
714
+ ```powershell
715
+ indraq login
716
+ indraq whoami
717
+ indraq password reset
718
+ indraq logout
719
+ ```
720
+
721
+ - `login`: interactive Cloud credentials; persistent Cloud session.
722
+ - `whoami`: check identity and role before using protected resources.
723
+ - `password reset`: supports email-OTP reset for Cloud, supported provider credentials, or all password-based targets. Use `indraq password reset --help` for flags.
724
+ - `logout`: revoke the current session on the server and locally.
725
+
726
+ ### 7.2 `init`
727
+
728
+ ```powershell
729
+ indraq init
730
+ indraq init C:\Projects\my-app
731
+ indraq init --skip-install
732
+ ```
733
+
734
+ Use **`init`** for a brand-new application. It can generate web project structure or use an official Expo/React Native generator. You may be asked about framework, Node version, backend port, optional integrations, or database settings depending on the project type.
735
+
736
+ `init` creates/links project metadata; it does **not** guarantee that optional DNS/proxy infrastructure is active unless you select/configure it. For a new mobile-only generator, follow the on-screen instruction to run mobile prebuild afterward.
737
+
738
+ ### 7.3 `project create`, `project link`, `project status`
739
+
740
+ ```powershell
741
+ indraq project create
742
+ indraq project create "My API" --kind backend --port 8000
743
+ indraq project list
744
+ indraq project link
745
+ indraq project status
746
+ ```
747
+
748
+ `project create` keeps existing source and creates a Cloud record for its components. Supported `--kind` values include `frontend`, `backend`, `fullstack`, `multiweb`, `mobile`, and `backend-mobile`. The wizard can choose deployment environments and the setup tasks to perform now.
749
+
750
+ `project link` connects a new local checkout to an accessible existing project instead of creating a duplicate Cloud project. `project status` is your read-only place to inspect what is registered.
751
+
752
+ ### 7.4 `project environments` and `project scopes`
753
+
754
+ ```powershell
755
+ indraq project environments
756
+ indraq project scopes --env production
757
+ indraq scope list
758
+ ```
759
+
760
+ - **Project environments** choose the actual web target servers your project is allowed to deploy to.
761
+ - **Project scopes** choose which AWS, GitHub Packages, Jenkins DEV/PROD, and NPM accounts the target environment uses.
762
+ - **Scope list** shows only resources you are assigned to.
763
+
764
+ A shared environment name is not necessarily the Jenkins stage: an admin can explicitly map the environment to Jenkins DEV or PROD.
765
+
766
+ ### 7.5 `setup` versus `prebuild`
767
+
768
+ | `indraq setup` | `indraq prebuild` |
769
+ |---|---|
770
+ | Full guided onboarding / repair | Infrastructure configuration for an existing linked project |
771
+ | Can help with login and project linking | Assumes the project is registered |
772
+ | Can include Dockerfile generation | Web checklist focuses on GHCR/Jenkins/Route53/NPM |
773
+ | At combined-project root, can run backend and mobile setup | Detects the current component context |
774
+
775
+ **Web prebuild setup checklist:** GitHub Packages + Jenkins are required for standard web deployment; Route53/NPM are optional. Link existing resources when appropriate rather than creating duplicates.
776
+
777
+ ```powershell
778
+ indraq prebuild
779
+ indraq prebuild --env my-server
780
+ indraq prebuild --all-targets
781
+ indraq prebuild --required-only
782
+ ```
783
+
784
+ `--required-only` means **skip optional DNS and proxy**, not “skip access checks”.
785
+
786
+ ### 7.6 `deploy`
787
+
788
+ ```powershell
789
+ indraq deploy
790
+ indraq deploy --env production
791
+ indraq deploy --all
792
+ indraq deploy --env production --select-scopes
793
+ ```
794
+
795
+ `deploy` is the web path: choose component(s), validate/generate missing Dockerfiles when offered, build Docker images, push them to GitHub Packages, and run Jenkins deployments. It streams the Jenkins console and waits for the result unless you use an independently configured direct Jenkins command with `--no-wait`.
796
+
797
+ **`--env` does not choose a `.env` file.** It selects the IndraQ infrastructure environment.
798
+
799
+ ### 7.7 `dockerfile create`
800
+
801
+ ```powershell
802
+ indraq dockerfile create
803
+ ```
804
+
805
+ Generates Docker artifacts for a supported application component when they are missing. Review the generated Dockerfile and `.dockerignore` before production deployment. Existing files are preserved where the generator is designed to avoid overwriting them.
806
+
807
+ ### 7.8 `configure`
808
+
809
+ ```powershell
810
+ indraq configure
811
+ ```
812
+
813
+ This is the interactive configuration home. It includes personal provider scope defaults, project scope bindings, infrastructure reconciliation, and **Mobile App settings**.
814
+
815
+ ```text
816
+ indraq configure
817
+ ├─ Choose default provider scope
818
+ ├─ Choose project provider scopes
819
+ ├─ Reconcile project infrastructure
820
+ └─ Mobile App settings
821
+ ├─ App name / Expo or React Native CLI
822
+ ├─ Version + Android versionCode
823
+ └─ Build output and profile for dev / staging / prod
824
+ ```
825
+
826
+ For mobile version management, automatic increment toggles are independent: app version and Android versionCode can each be ON or OFF. They advance only after successful native Jenkins builds.
827
+
828
+ ### 7.9 `jenkins pipelines` and `jenkins build`
829
+
830
+ ```powershell
831
+ indraq jenkins pipelines --stage dev
832
+ indraq jenkins build --stage dev
833
+ indraq jenkins build "My Pipeline" --stage prod
834
+ ```
835
+
836
+ Use these for **direct Jenkins job execution**, not automatic web project deployment. The CLI lists jobs visible to your provider identity and prompts for their declared parameters. `indraq jenkins build ... --no-wait` queues the job without following it to completion.
837
+
838
+ ### 7.10 `scope`, `user`, `access` and `logs`
839
+
840
+ ```powershell
841
+ indraq scope list
842
+ indraq scope describe
843
+ indraq scope default github-packages
844
+ indraq user list
845
+ indraq user scopes
846
+ indraq access add user
847
+ indraq logs
848
+ ```
849
+
850
+ - `scope`: identify which organization provider account you are allowed to use.
851
+ - `user`: manage Cloud identities and their scope assignments (role-dependent).
852
+ - `access`: grant/revoke project-specific AWS/NPM/Jenkins resource access with audit records.
853
+ - `logs`: inspect organizational audit records if permitted.
854
+
855
+ ### 7.11 `environment`, `dns`, `proxy`, `iam`, `healthcheck`, `npm-user`
856
+
857
+ These are **infrastructure/admin tools**. Use the guided project workflow for routine deployments. Direct commands are available for authorized diagnostics and management.
858
+
859
+ | Family | Example | Typical reason |
860
+ |---|---|---|
861
+ | Environment | `indraq environment list` | See public/internal IP targets |
862
+ | DNS | `indraq dns records --zone Z123` | Check an A record |
863
+ | Proxy | `indraq proxy list` | Inspect reverse proxy and SSL routing |
864
+ | AWS IAM | `indraq iam users` | Manage provider-native IAM users |
865
+ | Health check | `indraq healthcheck list` | Review Route53 health checks |
866
+ | NPM users | `indraq npm-user list` | Review reverse-proxy user accounts |
867
+
868
+ All direct commands still enforce the relevant IndraQ/project/provider permissions.
869
+
870
+ ---
871
+
872
+ ## 8. Web deployment: from code to server
873
+
874
+ ### 8.1 Where the application goes
875
+
876
+ ![Web deploy pipeline](docs/assets/web-deployment.svg)
877
+
878
+ ```mermaid
879
+ sequenceDiagram
880
+ actor Developer
881
+ participant CLI as IndraQ CLI
882
+ participant GHCR as GitHub Packages
883
+ participant JA as Jenkins A
884
+ participant JB as Jenkins B
885
+ Developer->>CLI: indraq deploy --all
886
+ CLI->>CLI: Verify project, targets, Dockerfiles, scopes
887
+ CLI->>GHCR: Build + push image once
888
+ GHCR-->>CLI: Immutable image digest
889
+ CLI->>JA: Deploy exact digest
890
+ JA-->>CLI: Build status + logs
891
+ CLI->>JB: Deploy same digest
892
+ JB-->>CLI: Build status + logs
893
+ CLI-->>Developer: Summary
894
+ ```
895
+
896
+ For multiple servers, the CLI builds **once** and submits the **same image digest** to each configured target sequentially. If a target fails, the command stops and reports it.
897
+
898
+ ### 8.2 What each service contributes
899
+
900
+ ```text
901
+ Code -> Docker image -> GitHub Packages -> Jenkins -> Running container
902
+ |
903
+ Public DNS (Route53) ---> Public IP ---> NPM proxy ---> Internal IP:port
904
+ ```
905
+
906
+ - **Docker image:** packaged application and runtime.
907
+ - **GitHub Packages:** stored image, available by tag and immutable digest.
908
+ - **Jenkins:** deploys the requested image on the selected server.
909
+ - **Route53:** makes your domain point at a public IP.
910
+ - **NPM:** forwards HTTPS to the correct internal server IP and port.
911
+
912
+ ### 8.3 Public versus private IPs
913
+
914
+ ```text
915
+ example.com
916
+ |
917
+ v
918
+ Route53 A record ──> External/Public IPv4
919
+ |
920
+ v
921
+ Nginx Proxy Manager
922
+ |
923
+ v
924
+ Internal/Private IPv4:PORT
925
+ |
926
+ v
927
+ App container
928
+ ```
929
+
930
+ **Do not swap them:** Route53 receives the environment's *external/public IPv4*, while NPM uses its *internal/private IPv4* as the upstream.
931
+
932
+ ### 8.4 Link existing versus create/reconcile
933
+
934
+ During **web** project prebuild, the CLI can offer both options for existing GHCR packages, Jenkins jobs, Route53 records, and NPM proxy hosts. **The shared mobile Jenkins job is always managed manually; IndraQ will not create it or offer a create option.** Linking means **record the relationship without recreating or intentionally modifying the external resource**; creating/reconciling may create or update its configuration.
935
+
936
+ Example:
937
+
938
+ ```text
939
+ GitHub Packages for backend:
940
+ ○ Create/reconcile package association
941
+ ● Link existing container package (do not modify)
942
+
943
+ Choose package: barakah-backend
944
+ ✓ Linked ghcr.io/organization/barakah-backend
945
+ ```
946
+
947
+ A recorded association does not prove that the selected image tag exists or that a future deployment will succeed. The deployment still needs valid credentials and a usable image.
948
+
949
+ ---
950
+
951
+ ## 9. Mobile builds and OTA updates
952
+
953
+ ### 9.1 Two separate workflows
954
+
955
+ ```mermaid
956
+ flowchart LR
957
+ App[Mobile source] --> Native{Did native dependencies or native config change?}
958
+ Native -- Yes --> J[Android Jenkins build]
959
+ J --> Baseline[Record compatible native baseline]
960
+ Native -- No, JS/assets only --> OTA[Create signed OTA update]
961
+ Baseline --> OTA
962
+ OTA --> Test[Target a test audience]
963
+ Test --> Release[Promote same tested release]
964
+ Release --> Device[Eligible installed apps on cold start]
965
+ ```
966
+
967
+ **Native build:** produces an APK or AAB through Jenkins. **OTA:** sends compatible JavaScript and asset changes without producing another APK/AAB. The CLI blocks OTA when the source's native fingerprint does not match a recorded successful native build.
968
+
969
+ ### 9.2 Supported Android build matrix
970
+
971
+ | Project type | Development | Staging | Production |
972
+ |---|---|---|---|
973
+ | **Expo** | Development Client APK | Release APK or Release AAB | Release APK or Release AAB |
974
+ | **React Native CLI** | Debug APK | Release APK or Release AAB | Release APK or Release AAB |
975
+
976
+ **Build profiles:**
977
+
978
+ | Profile | Meaning |
979
+ |---|---|
980
+ | `FAST` | Fresh source, reuse shared npm/Gradle caches |
981
+ | `CLEAN` | Clean project build state first |
982
+ | `FULL_RESET` | Reset project/Jenkins build caches for a deeper clean |
983
+
984
+ ### 9.3 Create a reusable mobile build environment
985
+
986
+ **Mobile build environment = which Jenkins controller to use.** It does **not** fix Development/Staging/Production. One server can compile any Android build mode; you choose the mode for each build.
987
+
988
+ ```powershell
989
+ indraq mobile environment list
990
+ # Administrator only (when adding a new build environment):
991
+ indraq mobile environment create
992
+ ```
993
+
994
+ On creation, the admin chooses a name, Jenkins DEV/PROD controller, and OTA channel. The legacy Cloud database retains a `build_type` field for compatibility, but **v2.7.9 ignores it when selecting a Jenkins build environment**. Existing `Immortility` works for all three modes. Normal developers still need permission to use the selected Jenkins provider scope.
995
+
996
+ ### 9.4 Guided Android builds (recommended)
997
+
998
+ ```powershell
999
+ cd C:\Projects\my-mobile-app
1000
+ indraq mobile build
1001
+ ```
1002
+
1003
+ ```mermaid
1004
+ flowchart TD
1005
+ A[indraq mobile build] --> B[Choose mobile environment / Jenkins server]
1006
+ B --> C{App type?}
1007
+ C --> D[Expo]
1008
+ C --> E[React Native CLI]
1009
+ D --> F{Build type?}
1010
+ E --> F
1011
+ F --> G[Development]
1012
+ F --> H[Staging]
1013
+ F --> I[Production]
1014
+ G --> J[Allowed APK output]
1015
+ H --> K[Release APK or AAB]
1016
+ I --> K
1017
+ J --> L[FAST / CLEAN / FULL_RESET]
1018
+ K --> L
1019
+ L --> M[Validate and show build plan]
1020
+ M --> N{Confirm?}
1021
+ N -- No --> O[Cancel, no build]
1022
+ N -- Yes --> P[Upload source to selected Jenkins server]
1023
+ P --> Q[Build APK/AAB and archive artifact]
1024
+ ```
1025
+
1026
+ An example interactive session:
1027
+
1028
+ ```text
1029
+ ? Mobile build environment / Jenkins server: Immortility — Jenkins PROD
1030
+ ? App type: Expo
1031
+ ? Build type: Production
1032
+ ? Build output: Release AAB
1033
+ ? Build profile: CLEAN
1034
+
1035
+ Build plan: Immortility | Expo | Production | Release AAB | CLEAN
1036
+ ? Create a source snapshot and start this Jenkins mobile build? Yes
1037
+ ```
1038
+
1039
+ **Preview only:**
1040
+
1041
+ ```powershell
1042
+ indraq mobile build --dry-run
1043
+ ```
1044
+
1045
+ **Specify values without repeated prompts:**
1046
+
1047
+ ```powershell
1048
+ indraq mobile build --env immortility --type expo --mode prod --output aab --profile clean
1049
+ indraq mobile build --env immortility --type expo --mode dev --profile fast
1050
+ indraq mobile build --env immortility --type native --mode staging --output apk --profile full-reset
1051
+ ```
1052
+
1053
+ **Framework note:** `--type native` means **React Native CLI** with an Android Gradle project. This release does not add pure Kotlin/Java Android Studio or iOS native compilation support.
1054
+
1055
+ Valid CLI flags: `--env`, `--type expo|native`, `--mode dev|staging|prod`, `--output dev-client|debug-apk|apk|aab`, `--profile fast|clean|full-reset`, `--dry-run`, `--verbose`, `--yes`.
1056
+
1057
+ **Legacy shortcuts still work:** `indraq build mobile:dev`, `indraq build mobile:staging`, `indraq build mobile:prod`, and their previous options. They are compatibility commands; use `indraq mobile build` for the complete interactive experience.
1058
+
1059
+ **Initial setup:** If the selected server has not been linked to the app, the wizard offers to run mobile Jenkins + OTA prebuild automatically. To do so manually:
1060
+
1061
+ ```powershell
1062
+ indraq mobile prebuild --env immortility --mode prod
1063
+ ```
1064
+
1065
+ **OTA isolation limitation:** The current Cloud API stores one active native OTA compatibility baseline per mobile environment/app pair. v2.7.9 uses different runtime identifiers (`<version>-indraq-dev`, `-staging`, `-prod`) so updates are never delivered across those build types. Switching build types on the **same** mobile environment replaces its active OTA baseline, which can temporarily prevent OTA updates to previously built modes. For *simultaneous, independent OTA releases* to Development, Staging and Production, create separate mobile environment records—these may all point to the **same Jenkins server**. You do **not** need another physical server.
1066
+
1067
+ Source snapshots exclude `.git`, `.indraq`, `node_modules`, caches and build outputs; root `.env` uploads separately. Release outputs require a root `.env` under the current Jenkinsfile policy.
1068
+
1069
+ ### 9.5 Understand version fields correctly
1070
+
1071
+ | Field | Example | Where it lives | Who controls it |
1072
+ |---|---|---|---|
1073
+ | App version (`expo.version`) | `1.0.0` | Expo app config | `indraq configure` version setting |
1074
+ | Android `versionCode` | `20` | `expo.android.versionCode` | `indraq configure` versionCode setting |
1075
+ | Apple iOS `buildNumber` | `"15"` | `expo.ios.buildNumber` | **Currently edit manually in Expo app config** |
1076
+ | Jenkins job build number | `#42` | Jenkins job history | Jenkins; shared across builds |
1077
+
1078
+ **Current scope:** v2.7.9 Android build commands manage app version and Android versionCode, not Apple's iOS `buildNumber`. An iOS build-number field in `app.json` does **not** turn these Android build commands into an iOS native build pipeline.
1079
+
1080
+ Example Expo config **snippet** (merge it into your existing `expo` object; do not replace the whole file):
1081
+
1082
+ ```json
1083
+ {
1084
+ "expo": {
1085
+ "version": "1.0.0",
1086
+ "ios": { "buildNumber": "15" },
1087
+ "android": { "versionCode": 20 }
1088
+ }
1089
+ }
1090
+ ```
1091
+
1092
+ To edit the two automated settings:
1093
+
1094
+ ```text
1095
+ indraq configure
1096
+ -> Mobile App settings
1097
+ -> Version & versionCode
1098
+ -> Change Version or versionCode
1099
+ -> Set auto-increment ON/OFF independently
1100
+ ```
1101
+
1102
+ Successful builds can advance enabled counters; failed/cancelled builds do not consume a version. The tool writes the next values locally, so commit the intended `app.json` and `.indraq/mobile.json` changes (not secret files).
1103
+
1104
+ ### 9.6 OTA lifecycle
1105
+
1106
+ ```mermaid
1107
+ stateDiagram-v2
1108
+ [*] --> NativeBaseline: Successful compatible native build
1109
+ NativeBaseline --> TestRelease: send update to test users
1110
+ TestRelease --> Released: release update
1111
+ TestRelease --> Paused: pause
1112
+ Released --> Paused: pause
1113
+ Released --> Rollback: rollback
1114
+ Rollback --> Released: previous known-good assets
1115
+ ```
1116
+
1117
+ ```powershell
1118
+ indraq mobile send update --app "My App" --env immortility
1119
+ indraq mobile metrics --app "My App"
1120
+ indraq mobile release update --app "My App"
1121
+ indraq mobile pause --app "My App"
1122
+ indraq mobile rollback --app "My App"
1123
+ ```
1124
+
1125
+ - **Send update:** build an immutable signed JS/assets release. Select enrolled QA groups, named tester installations, other registered installations, a percentage rollout, or everyone. No per-app email/phone integration is required.
1126
+ - **Release update:** promote the **exact tested release**; no bundle rebuild.
1127
+ - **Pause:** pause an active release.
1128
+ - **Rollback:** republish previous known-good content.
1129
+ - **Metrics:** see installations, manifests, downloads, launches, failures, and rollback activity.
1130
+
1131
+ Eligible installed apps check at **cold startup**; a downloaded compatible update may cause an app reload before normal use.
1132
+
1133
+ ---
1134
+
1135
+ ## 10. Environments, scopes, and permissions
1136
+
1137
+ ### 10.1 What is a provider scope?
1138
+
1139
+ A **scope** is one named provider connection, such as:
1140
+
1141
+ ```text
1142
+ GitHub Packages ── GHCR IndraQ
1143
+ Jenkins DEV ── Jenkins IndraQ
1144
+ Jenkins PROD ── Jenkins Immortility
1145
+ AWS ── AWS Production
1146
+ NPM ── Proxy Server A
1147
+ ```
1148
+
1149
+ A project may use different scopes on different deployment environments. A personal default helps when multiple scopes are available but does not give extra privileges.
1150
+
1151
+ ```mermaid
1152
+ flowchart TB
1153
+ Org[Organization] --> U[Cloud user]
1154
+ Org --> P[Project]
1155
+ U --> S[Assigned provider scope]
1156
+ U --> R[Project role / resource grant]
1157
+ S --> Target[Provider identity + USE or MANAGE]
1158
+ P --> Env[Project environment]
1159
+ Env --> Target
1160
+ R --> Action[Permitted operation]
1161
+ Target --> Action
1162
+ ```
1163
+
1164
+ ### 10.2 Roles and abilities
1165
+
1166
+ The platform checks **more than one permission**. Your organization role, project permission, provider-scope permission, and provider-native identity must all permit the attempted action.
1167
+
1168
+ | Action | USER | MANAGER | ADMIN |
1169
+ |---|---|---|---|
1170
+ | Log in, view assigned scopes | If assigned | If assigned | Yes, subject to scope setup |
1171
+ | Deploy an assigned project | With WRITE + appropriate scope access | With access | With access |
1172
+ | Create organization provider scopes | No | No | Yes |
1173
+ | Create/update shared web/mobile environments | No | No | Yes |
1174
+ | Add a normal user to a MANAGE scope | No | On scopes they manage | Yes |
1175
+ | Change organization roles | No | Limited user management | Admin-only role changes |
1176
+ | Delete Cloud project with external cleanup | No | With required project/scope permissions | With required project/scope permissions |
1177
+
1178
+ **USE** means permitted use of an assigned provider resource, not unrestricted administration. **MANAGE** allows scoped management actions. Native AWS/Jenkins/NPM/GitHub permissions can further restrict individual operations.
1179
+
1180
+ ### 10.3 Why permissions exist
1181
+
1182
+ ```text
1183
+ User identity ──> Project WRITE? ──> Provider MANAGE/USE?
1184
+ |
1185
+ v
1186
+ Provider-native permission?
1187
+ |
1188
+ v
1189
+ Operation
1190
+ ```
1191
+
1192
+ Project membership and provider access are intentionally independent. For example, a developer may see a project but lack the Jenkins scope needed to deploy it.
1193
+
1194
+ ### 10.4 Admin setup order
1195
+
1196
+ ```mermaid
1197
+ flowchart LR
1198
+ A[Create shared environment] --> B[Create provider scopes]
1199
+ B --> C[Assign users / memberships]
1200
+ C --> D[Choose project scope bindings]
1201
+ D --> E[Run prebuild]
1202
+ E --> F[Build and deploy]
1203
+ ```
1204
+
1205
+ Admin examples:
1206
+
1207
+ ```powershell
1208
+ indraq environment create
1209
+ indraq scope create github-packages
1210
+ indraq scope create jenkins-dev
1211
+ indraq scope create npm
1212
+ indraq scope create aws
1213
+ indraq mobile environment create
1214
+ ```
1215
+
1216
+ User/manager scope selection examples:
1217
+
1218
+ ```powershell
1219
+ indraq scope list
1220
+ indraq scope describe
1221
+ indraq scope default github-packages
1222
+ indraq project scopes --env production
1223
+ ```
1224
+
1225
+ ### 10.5 Audit reasons
1226
+
1227
+ Normal creation/setup uses safe automatic audit reasons in supported flows. Sensitive modifications/deletions may ask for a reason. Audit information helps explain **who changed what, where, and why**.
1228
+
1229
+ ---
1230
+
1231
+ ## 11. Safe project deletion
1232
+
1233
+ Deleting a Cloud project is **not the same as deleting every external resource**. The CLI asks you to select which recognized, associated resources should also be deleted.
1234
+
1235
+ ![Safe deletion flow](docs/assets/cleanup.svg)
1236
+
1237
+ ```powershell
1238
+ indraq project delete
1239
+ ```
1240
+
1241
+ Example selection:
1242
+
1243
+ ```text
1244
+ Delete project: my-old-app
1245
+ Choose external resources to DELETE (unchecked = KEEP):
1246
+
1247
+ [ ] GitHub Packages — ghcr.io/org/my-old-app
1248
+ [x] Jenkins — my-old-app-api
1249
+ [x] NPM — api.example.com
1250
+ [ ] Route53 — api.example.com
1251
+ ```
1252
+
1253
+ **Default is KEEP.** The deletion plan appears before confirmation, and the CLI asks you to confirm the project identity and provide an audit reason. A resource shared by another IndraQ project must not be deleted through this flow. Shared mobile system jobs are protected.
1254
+
1255
+ | Selected action | What happens |
1256
+ |---|---|
1257
+ | KEEP | External resource is not deleted |
1258
+ | DELETE GHCR package | Removes the **entire container package**, including **all tags/versions** |
1259
+ | DELETE Jenkins job | Deletes the associated supported per-project job; not shared system jobs |
1260
+ | DELETE Route53 record | Deletes matching associated Route53 A record set(s) |
1261
+ | DELETE NPM proxy | Deletes the matching associated NPM proxy host |
1262
+ | Provider deletion fails | Cloud project is retained so you can repair and retry |
1263
+
1264
+ **What is not automatically removed:** live Docker containers, Route53 health checks, shared NPM certificates, and other unlisted provider resources.
1265
+
1266
+ When several NPM scopes exist, select the scope that really owns the proxy and verify its ID/domain. For legacy GHCR scopes missing owner type, the CLI checks the GitHub owner identity before choosing the correct delete endpoint. A token must still have the correct provider deletion permission.
1267
+
1268
+ ### Archive instead of delete
1269
+
1270
+ ```powershell
1271
+ indraq project archive
1272
+ indraq project restore
1273
+ ```
1274
+
1275
+ Archiving is useful when a project should stop deployment mutations but its metadata should remain available. Use permanent deletion only when you no longer need the project and have reviewed its external dependencies.
1276
+
1277
+ ---
1278
+
1279
+ ## 12. Configuration files and secrets
1280
+
1281
+ ### 12.1 Typical local files
1282
+
1283
+ ```text
1284
+ my-project/
1285
+ ├── frontend/ # optional
1286
+ ├── backend/ # optional
1287
+ ├── mobile/ # optional
1288
+ │ ├── app.json # Expo config (when using Expo)
1289
+ │ └── .indraq/
1290
+ │ └── mobile.json # mobile settings; commit if intended
1291
+ └── .indraq/
1292
+ └── project.json # local Cloud project reference
1293
+ ```
1294
+
1295
+ The CLI saves the **Cloud project ID** locally; infrastructure associations and reusable provider credentials are held by the Cloud control plane. The exact layout depends on whether this is a single-component or combined project.
1296
+
1297
+ ### 12.2 Keep and exclude the right files
1298
+
1299
+ | Item | Commit to Git? | Explanation |
1300
+ |---|---|---|
1301
+ | Source code and app config | Yes, after review | Needed by teammates/builds |
1302
+ | `.indraq/mobile.json` | **Yes**, in this workflow | Preserves per-project mobile defaults and version settings |
1303
+ | `.indraq/project.json` | Follow team policy | Stores project identity, not provider secrets |
1304
+ | `.env` and secret values | **No** | Keep out of Git and public archives |
1305
+ | OTA private signing keys / tokens | **No** | Protect credential material |
1306
+ | `node_modules`, caches, build outputs | Usually no | Rebuild/reinstall as needed |
1307
+
1308
+ If the CLI reports **`.indraq/mobile.json is ignored by Git`**, change the `.gitignore` rule so the *specific* mobile config is tracked, without exposing secrets:
1309
+
1310
+ ```gitignore
1311
+ # Keep private IndraQ files ignored by default
1312
+ .indraq/*
1313
+ !.indraq/mobile.json
1314
+
1315
+ # Mobile subfolder in combined projects
1316
+ mobile/.indraq/*
1317
+ !mobile/.indraq/mobile.json
1318
+
1319
+ # Secrets
1320
+ .env
1321
+ .env.*
1322
+ *.pem
1323
+ *.key
1324
+ ```
1325
+
1326
+ If your repository already has an `.indraq/` directory ignore rule, it may also require unignoring the parent directory before Git can add `mobile.json`. Verify the actual result with `git check-ignore -v mobile/.indraq/mobile.json` (or the correct path). Avoid committing certificates or private keys alongside the config.
1327
+
1328
+ ### 12.3 `.env` versus `--env`
1329
+
1330
+ **They are unrelated.**
1331
+
1332
+ ```text
1333
+ .env Application secrets/config file
1334
+ --env <environment-name> IndraQ deployment or mobile environment selector
1335
+ ```
1336
+
1337
+ The mobile source ZIP excludes `.env`; when present, the CLI uploads it separately to Jenkins. This does not make `.env` safe to commit or share.
1338
+
1339
+ ### 12.4 Expo `app.json` comments
1340
+
1341
+ The CLI v2.7.9 config helper accepts commented Expo `app.json` content and can normalize it before OTA setup. When normalization is needed it preserves a backup in `.indraq/backups/`. Review the diff before committing automatically rewritten config.
1342
+
1343
+ ---
1344
+
1345
+ ## 13. Troubleshooting
1346
+
1347
+ Use `indraq doctor`, `indraq whoami`, `indraq project status`, and `indraq scope list` first. They frequently explain issues before a destructive retry is needed.
1348
+
1349
+ | Symptom | Meaning | Recommended action |
1350
+ |---|---|---|
1351
+ | `indraq` not recognized | CLI not on PATH or not installed | Check `npm install -g indraq_cli`, restart terminal, run `indraq doctor` |
1352
+ | Cloud login rejected | Account/session issue | Try `indraq login` or authorized `indraq password reset` |
1353
+ | `No provider scope` | User/project lacks an assigned provider connection | Check `scope list`; ask manager/admin to grant access or bind a scope |
1354
+ | GHCR package unavailable | Wrong scope, owner, name or permissions | Verify actual package in correct scope and association |
1355
+ | Dockerfile missing | Project component needs Docker setup | Run `indraq dockerfile create` or allow deploy to generate it |
1356
+ | Host port unavailable | Port may already be held by a container/process | Check the owner, choose a free port; don't blindly reuse an occupied port |
1357
+ | Jenkins says `job is not parameterized` (HTTP 400) | Mobile job does not yet expose required parameters | Have a Jenkins administrator fix the existing job and the File Parameter plugin manually; IndraQ never edits the job |
1358
+ | `No active mobile environment exists for Production` | Older CLI still filtered servers by build type | Upgrade to v2.7.9; use `indraq mobile build` and select any authorized mobile server |
1359
+ | `Mobile OTA/Jenkins prebuild is incomplete` | Native build attempted before mobile prebuild/registration | Run `indraq mobile prebuild --env <slug>` |
1360
+ | `Unexpected token '/'` in `app.json` | Strict JSON parser encountered comments (older CLI) | Upgrade to v2.7.9, review the source config and normalization backup |
1361
+ | Windows `Invalid project root` during signing | Older Windows argument-handling bug | Upgrade CLI; rerun mobile prebuild from correct mobile project path |
1362
+ | OTA native fingerprint mismatch | Native config/dependencies changed after last compatible native build | Create a fresh native build, then retry OTA |
1363
+ | NPM cleanup asks to choose scope | Multiple NPM scopes may exist | Verify and explicitly select the correct one; never guess |
1364
+ | GHCR cleanup says owner type missing | Legacy scope configuration/identity needs resolution | Use updated CLI; verify GitHub owner and token rights |
1365
+ | Jenkins/proxy 502 during deploy | Network response may be lost after job began | Check Jenkins before retrying; CLI attempts safe reconnect |
1366
+ | `mobile build:prod` unknown | This shortcut is not a command | Use `indraq mobile build --mode prod` or legacy `indraq build mobile:prod` |
1367
+ | `.indraq/mobile.json ignored by Git` | Settings will be missing after Git clone | Adjust `.gitignore` carefully and commit `mobile.json` |
1368
+
1369
+ ### 13.1 Jenkins plugin requirements for mobile
1370
+
1371
+ The shared, manually maintained Jenkins mobile job receives a **source bundle** and (when applicable) an **environment file** as file parameters. If Jenkins returns `HTTP 400 ... is not parameterized`, ensure the required Jenkinsfile has been loaded and the **File Parameter** plugin is installed. If Jenkins has not loaded its parameters yet, have a Jenkins administrator initialize or repair it; IndraQ does not attempt any Jenkins configuration changes.
1372
+
1373
+ ### 13.2 If deployment looks stuck
1374
+
1375
+ ```text
1376
+ CLI started Jenkins request
1377
+ |
1378
+ v
1379
+ Response lost?
1380
+ |
1381
+ v
1382
+ Check existing Jenkins queue/build before retry
1383
+ |
1384
+ v
1385
+ Resume / inspect logs instead of starting a duplicate
1386
+ ```
1387
+
1388
+ IndraQ tries to avoid repeating a Jenkins POST when the reverse proxy returns an uncertain timeout or 502/503/504. If the CLI cannot safely identify the accepted job, inspect Jenkins manually before retrying.
1389
+
1390
+ ### 13.3 What to send when reporting a bug
1391
+
1392
+ ```text
1393
+ CLI version: indraq --version
1394
+ Operating system: Windows / macOS / Linux
1395
+ Current directory: pwd (PowerShell: Get-Location)
1396
+ Exact command: indraq ...
1397
+ Relevant project type: frontend / backend / mobile / backend-mobile ...
1398
+ Error message: paste the last relevant 20–50 lines
1399
+ Secrets: remove passwords, tokens, .env values, and private keys
1400
+ ```
1401
+
1402
+ ---
1403
+
1404
+ ## 14. FAQs, glossary, and developer notes
1405
+
1406
+ ### Frequently asked questions
1407
+
1408
+ <details>
1409
+ <summary><strong>Do I need to know Jenkins or AWS to deploy a project?</strong></summary>
1410
+
1411
+ Not for the ordinary guided flow. An admin must have configured the shared environments, scopes, credentials, and permissions. Developers then use `indraq setup`, `indraq prebuild`, and `indraq deploy`.
1412
+
1413
+ </details>
1414
+
1415
+ <details>
1416
+ <summary><strong>Can I link existing Jenkins, Route53, NPM, or GitHub Packages resources?</strong></summary>
1417
+
1418
+ Yes, the web prebuild workflow can choose an existing association instead of creating or reconciling it. Check provider scope and identity carefully, especially for legacy projects.
1419
+
1420
+ </details>
1421
+
1422
+ <details>
1423
+ <summary><strong>Can I deploy the same application to two servers?</strong></summary>
1424
+
1425
+ Yes. Use `indraq project environments` to configure allowed targets, then `indraq deploy --all`. The same immutable image digest is sent to each server's Jenkins controller.
1426
+
1427
+ </details>
1428
+
1429
+ <details>
1430
+ <summary><strong>Can I build an iOS IPA on Windows using `indraq build mobile:prod`?</strong></summary>
1431
+
1432
+ No. The v2.7.9 `mobile:dev`, `mobile:staging`, and `mobile:prod` commands are **Android APK/AAB** workflows. Apple signing and native iOS builds need a separate supported macOS/iOS build arrangement. Expo `ios.buildNumber` can be edited manually in the app configuration.
1433
+
1434
+ </details>
1435
+
1436
+ <details>
1437
+ <summary><strong>Does an OTA update require a new native binary?</strong></summary>
1438
+
1439
+ Not for JavaScript/assets-only changes that match a recorded successful compatible native baseline. Native dependencies or native configuration changes do require a new compatible binary first.
1440
+
1441
+ </details>
1442
+
1443
+ <details>
1444
+ <summary><strong>Does deleting a project delete its live application container?</strong></summary>
1445
+
1446
+ No, deployed containers are not automatically removed by the selective external cleanup. Review your actual running infrastructure separately.
1447
+
1448
+ </details>
1449
+
1450
+ <details>
1451
+ <summary><strong>Why does my Jenkins build number differ from the Android versionCode?</strong></summary>
1452
+
1453
+ Jenkins `#42` is a globally increasing job execution ID. Android `versionCode` is native application metadata. They are independent. Apple `ios.buildNumber` is a third, separate native field.
1454
+
1455
+ </details>
1456
+
1457
+ ### Essential glossary
1458
+
1459
+ | Term | Meaning |
1460
+ |---|---|
1461
+ | **CLI** | Command-line interface: commands typed in a terminal |
1462
+ | **Cloud project** | Central record of an application, components, members, and resource links |
1463
+ | **Component** | Independently built part of a project (frontend, backend, mobile) |
1464
+ | **Environment** | Named deployment server or mobile build/OTA configuration |
1465
+ | **Scope** | Authorized provider account/server connection |
1466
+ | **GHCR** | GitHub Container Registry (`ghcr.io`), part of GitHub Packages |
1467
+ | **Jenkins job** | Automated build or deployment pipeline |
1468
+ | **Docker image** | Packaged application and runtime |
1469
+ | **Digest** | Immutable identifier of the exact Docker image contents |
1470
+ | **Route53** | AWS managed DNS service |
1471
+ | **NPM proxy** | Nginx Proxy Manager host, not the Node package manager |
1472
+ | **APK** | Android installable package |
1473
+ | **AAB** | Android App Bundle for store distribution |
1474
+ | **OTA** | Over-the-air update of compatible app JavaScript/assets |
1475
+ | **Native fingerprint** | Compatibility identifier derived from native app dependencies/configuration |
1476
+ | **Audit reason** | Explanation recorded for an authorized change |
1477
+
1478
+ ### For contributors maintaining IndraQ CLI
1479
+
1480
+ This README describes the **published command behavior**, not private server setup steps. If you change the command surface, update this file and the in-terminal help together.
1481
+
1482
+ ```powershell
1483
+ # In the IndraQ CLI source repository
1484
+ npm install
1485
+ npm run build
1486
+ npm test
1487
+ npm publish --dry-run
1488
+ ```
1489
+
1490
+ Cloud API has its own dependency/build step:
1491
+
1492
+ ```powershell
1493
+ cd cloud-api
1494
+ npm install
1495
+ npm run build
1496
+ ```
1497
+
1498
+ Only publish after a clean dependency-backed TypeScript build, tests, and an npm package-content audit. The CLI and Cloud API need compatible versions for server-side authorization changes.
1499
+
1500
+ ---
1501
+
1502
+ <div align="center">
1503
+
1504
+ **IndraQ CLI — build once, deploy deliberately, and manage infrastructure with clear permissions.**
1505
+
1506
+ Maintained by **IndraQ Innovations Private Limited** · Documented for CLI **v2.8.0**
1507
+
1508
+ </div>
1509
+
1510
+
1511
+ ## Fixing Jenkins HTTP 400: job is not parameterized
1512
+
1513
+ Mobile build uses `indraq mobile build`. In v2.7.9, the CLI checks that the chosen Jenkins job has required parameters **before** uploading the source snapshot. If parameters are missing, it stops immediately and asks you to repair the job manually in Jenkins; it never edits any Pipeline setting.
1514
+
1515
+ `indraq mobile prebuild --env immortility` validates the pre-existing mobile Jenkins job and required parameters without changing Jenkins. The Jenkins File Parameter plugin (`file-parameters`) is required for `SOURCE_BUNDLE` and `ENV_FILE`. Users need Jenkins Job/Read and Job/Build permissions. All Jenkins job changes must be made manually by a Jenkins administrator.
1516
+
1517
+ If you still see HTTP 400, have a Jenkins administrator check that the job is parameterized and the File Parameter plugin is active. IndraQ will not attempt automatic repair.
1518
+
1519
+
1520
+ ## Jenkins mobile Pipeline protection (v2.8.0)
1521
+
1522
+ For the existing shared job `Mobile app Cli build`, **IndraQ never replaces your Jenkins Pipeline script** during `indraq mobile prebuild` or `indraq mobile build`.
1523
+
1524
+ - `indraq mobile build` **never modifies Jenkins job configuration**. It validates parameters, uploads the source, and starts the existing job. If required parameters are missing, it stops and asks a Jenkins administrator to repair the job manually.
1525
+ - `indraq mobile prebuild` **never creates or changes a Jenkins job**. It only verifies the existing Pipeline job, parameters and access, then performs IndraQ OTA configuration. Missing or incorrect job parameters cause a clear error; fix them directly in Jenkins.
1526
+ - If a required parameter already exists with an incompatible type or choice list, prebuild **stops instead of overwriting it**. An administrator should resolve the conflict explicitly in Jenkins.
1527
+ - Updating the Pipeline script remains a manual Jenkins operation. The CLI does **not** automatically deploy new pipeline script revisions into an existing job.
1528
+
1529
+ > Deployment: deploy Cloud API **v1.3.7** before using CLI **v2.8.0**.
1530
+
1531
+ ### Mobile Jenkins job: manual setup and repair
1532
+
1533
+ Before using IndraQ mobile prebuild/build, an administrator must configure an existing Jenkins **Pipeline** job named exactly `Mobile app Cli build`. Install the **File Parameter** plugin and load your maintained Pipeline script in Jenkins. IndraQ **never** submits a script, calls `createItem`, writes `config.xml`, or adds/changes job parameters.
1534
+
1535
+ | Required Jenkins parameters | Type |
1536
+ |---|---|
1537
+ | `SOURCE_BUNDLE`, `ENV_FILE` | `stashedFile` (File Parameter plugin) |
1538
+ | `PROJECT_ID`, `APP_NAME`, `APP_VERSION`, `APP_VERSION_CODE`, `SOURCE_SHA256`, `SOURCE_REVISION` | String |
1539
+ | `PROJECT_TYPE` | Choice: Expo, React Native CLI |
1540
+ | `BUILD_ENVIRONMENT` | Choice: Development, Staging, Production |
1541
+ | `BUILD_OUTPUT` | Choice: Development Client, Debug APK, Release APK, Release AAB |
1542
+ | `BUILD_PROFILE` | Choice: FAST, CLEAN, FULL_RESET |
1543
+ | `SOURCE_DIRTY`, `VERBOSE_BUILD` | Boolean |
1544
+
1545
+ The CLI reads the job type, enabled/buildable status, parameters, file types and choices. If invalid, it prints what needs manual repair **before uploading any source**. If valid, the build uses only Jenkins' `buildWithParameters` endpoint, streams the output, and leaves job configuration untouched. A real build naturally creates build history/artifacts, not Jenkins job configuration changes.
1546
+
1547
+ **Older CLI versions:** Cloud API v1.3.7 retains the Jenkins read-only protections introduced in v1.3.5. It rejects the legacy create/repair mobile operations with HTTP 409, so older CLI clients cannot modify the shared mobile job through IndraQ Cloud either.