update official-docker-image spec

.kiro/specs/official-docker-image/design.md

@@ -12,13 +12,14 @@
 
 - Up to 95% CVE reduction through DHI base image adoption
 - **Fully shell-free TypeScript entrypoint** — Node.js 24 native TypeScript execution (type stripping), maintaining the minimized attack surface of the DHI runtime as-is
-- Memory management via 3-tier fallback: `GROWI_HEAP_SIZE` / cgroup auto-calculation / V8 default
+- Memory management via 3-tier fallback: `V8_MAX_HEAP_SIZE` / cgroup auto-calculation / V8 default
+- Environment variable names aligned with V8 option names (`V8_MAX_HEAP_SIZE`, `V8_OPTIMIZE_FOR_SIZE`, `V8_LITE_MODE`)
 - Improved build cache efficiency through the `turbo prune --docker` pattern
 - Privilege drop via gosu → `process.setuid/setgid` (Node.js native)
 
 ### Non-Goals
 
-- Changes to Kubernetes manifests / Helm charts (GROWI.cloud `GROWI_HEAP_SIZE` configuration is out of scope)
+- Changes to Kubernetes manifests / Helm charts (GROWI.cloud `V8_MAX_HEAP_SIZE` configuration is out of scope)
 - Application code changes (adding gc(), migrating to .pipe(), etc. are separate specs)
 - Updating docker-compose.yml (documentation updates only)
 - Support for Node.js versions below 24
@@ -100,12 +101,12 @@ graph TB
 ```mermaid
 flowchart TD
     Start[Container Start<br>as root via node entrypoint.ts] --> Setup[Directory Setup<br>fs.mkdirSync + symlinkSync + chownSync]
-    Setup --> HeapCalc{GROWI_HEAP_SIZE<br>is set?}
-    HeapCalc -->|Yes| UseEnv[Use GROWI_HEAP_SIZE]
+    Setup --> HeapCalc{V8_MAX_HEAP_SIZE<br>is set?}
+    HeapCalc -->|Yes| UseEnv[Use V8_MAX_HEAP_SIZE]
     HeapCalc -->|No| CgroupCheck{cgroup limit<br>detectable?}
     CgroupCheck -->|Yes| AutoCalc[Auto-calculate<br>60% of cgroup limit]
     CgroupCheck -->|No| NoFlag[No heap flag<br>V8 default]
-    UseEnv --> OptFlags[Check GROWI_OPTIMIZE_MEMORY<br>and GROWI_LITE_MODE]
+    UseEnv --> OptFlags[Check V8_OPTIMIZE_FOR_SIZE<br>and V8_LITE_MODE]
     AutoCalc --> OptFlags
     NoFlag --> OptFlags
     OptFlags --> LogFlags[console.log applied flags]
@@ -162,7 +163,9 @@ flowchart LR
 |-----------|-------------|--------|-----------------|
 | Dockerfile | Infrastructure | 5-stage Docker image build definition | DHI images, turbo, pnpm |
 | docker-entrypoint.ts | Infrastructure | Container startup initialization (TypeScript) | Node.js fs/child_process, cgroup fs |
+| docker-entrypoint.spec.ts | Infrastructure | Unit tests for entrypoint | vitest |
 | Dockerfile.dockerignore | Infrastructure | Build context filter | — |
+| README.md | Documentation | Docker Hub image documentation | — |
 | buildspec.yml | CI/CD | CodeBuild build definition | AWS Secrets Manager, dhi.io |
 
 ### Dockerfile
@@ -194,22 +197,31 @@ flowchart LR
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `GROWI_HEAP_SIZE` | int (MB) | (unset) | Explicitly specify the --max-heap-size value for Node.js |
-| `GROWI_OPTIMIZE_MEMORY` | `"true"` / (unset) | (unset) | Enable the --optimize-for-size flag |
-| `GROWI_LITE_MODE` | `"true"` / (unset) | (unset) | Enable the --lite-mode flag |
+| `V8_MAX_HEAP_SIZE` | int (MB) | (unset) | Explicitly specify the --max-heap-size value for Node.js |
+| `V8_OPTIMIZE_FOR_SIZE` | `"true"` / (unset) | (unset) | Enable the --optimize-for-size flag |
+| `V8_LITE_MODE` | `"true"` / (unset) | (unset) | Enable the --lite-mode flag |
+
+> **Naming Convention**: Environment variable names are aligned with their corresponding V8 option names (`--max-heap-size`, `--optimize-for-size`, `--lite-mode`) prefixed with `V8_`. This improves discoverability and self-documentation compared to the previous `GROWI_`-prefixed names.
 
 **Batch Contract**
 - **Trigger**: On container startup (`ENTRYPOINT ["node", "/docker-entrypoint.ts"]`)
-- **Input validation**: GROWI_HEAP_SIZE (positive int, empty = unset), GROWI_OPTIMIZE_MEMORY/GROWI_LITE_MODE (only `"true"` is valid), cgroup v2 (`memory.max`: numeric or `"max"`), cgroup v1 (`memory.limit_in_bytes`: numeric, large value = unlimited)
+- **Input validation**: V8_MAX_HEAP_SIZE (positive int, empty = unset), V8_OPTIMIZE_FOR_SIZE/V8_LITE_MODE (only `"true"` is valid), cgroup v2 (`memory.max`: numeric or `"max"`), cgroup v1 (`memory.limit_in_bytes`: numeric, large value = unlimited)
 - **Output**: Node flags passed directly as arguments to `child_process.spawn`
 - **Idempotency**: Executed on every restart, safe via `fs.mkdirSync({ recursive: true })`
 
+### README.md
+
+**Responsibilities & Constraints**
+- Docker Hub image documentation (published to hub.docker.com/r/growilabs/growi)
+- Document the V8 memory management environment variables under Configuration > Environment Variables section
+- Include variable name, type, default, and description for each: `V8_MAX_HEAP_SIZE`, `V8_OPTIMIZE_FOR_SIZE`, `V8_LITE_MODE`
+
 ## Error Handling
 
 | Error | Category | Response |
 |-------|----------|----------|
 | cgroup file read failure | System | Warn and continue with no flag (V8 default) |
-| GROWI_HEAP_SIZE is invalid | User | Warn and continue with no flag (container still starts) |
+| V8_MAX_HEAP_SIZE is invalid | User | Warn and continue with no flag (container still starts) |
 | Directory creation/permission failure | System | `process.exit(1)` — check volume mount configuration |
 | Migration failure | Business Logic | `execFileSync` throws → `process.exit(1)` — Docker/k8s restarts |
 | App process abnormal exit | System | Propagate child process exit code |

.kiro/specs/official-docker-image/research.md

@@ -221,6 +221,28 @@
   - All external references (CI/CD, GitHub Actions) already use the `apps/app/docker/` path and require no changes
   - The `codebuild/` directory and `README.md` are maintained as-is within `docker/`
 
+### Environment Variable Renaming: GROWI_ prefix → V8_ prefix
+
+- **Context**: The initial implementation used `GROWI_HEAP_SIZE`, `GROWI_OPTIMIZE_MEMORY`, and `GROWI_LITE_MODE` as environment variable names. These names obscure the relationship between the env var and the underlying V8 flag it controls
+- **Motivation**: Align environment variable names with the actual V8 option names they map to, improving discoverability and self-documentation
+- **Mapping**:
+  | Old Name | New Name | V8 Flag |
+  |----------|----------|---------|
+  | `GROWI_HEAP_SIZE` | `V8_MAX_HEAP_SIZE` | `--max-heap-size` |
+  | `GROWI_OPTIMIZE_MEMORY` | `V8_OPTIMIZE_FOR_SIZE` | `--optimize-for-size` |
+  | `GROWI_LITE_MODE` | `V8_LITE_MODE` | `--lite-mode` |
+- **Benefits**:
+  - Users can immediately understand which V8 flag each variable controls
+  - Naming convention is consistent: `V8_` prefix + option name in UPPER_SNAKE_CASE
+  - No need to consult documentation to understand the mapping
+- **Impact scope**:
+  - `docker-entrypoint.ts`: Code changes (env var reads, comments, log messages)
+  - `docker-entrypoint.spec.ts`: Test updates (env var references in test cases)
+  - `README.md`: Add documentation for the new environment variables
+  - `design.md`, `requirements.md`, `tasks.md`: Spec document updates
+- **Breaking change**: Yes — users who have configured `GROWI_HEAP_SIZE`, `GROWI_OPTIMIZE_MEMORY`, or `GROWI_LITE_MODE` in their docker-compose.yml or deployment configs will need to update to the new names. This is acceptable as these variables were introduced in the same release (v7.5.x) and have not been published yet
+- **Implications**: No backward compatibility shim needed since the variables are new in this version
+
 ## Risks & Mitigations
 
 - **Stability of Node.js 24 native TypeScript execution**: Type stripping was unflagged in Node.js 23. It is a stable feature in Node.js 24. However, non-erasable syntax such as enum cannot be used -> Use only interface/type

.kiro/specs/official-docker-image/spec.json

@@ -1,10 +1,9 @@
 {
   "feature_name": "official-docker-image",
   "created_at": "2026-02-20T00:00:00.000Z",
-  "updated_at": "2026-02-24T12:00:00.000Z",
+  "updated_at": "2026-02-24T15:30:00.000Z",
   "language": "en",
-  "phase": "implementation-complete",
-  "cleanup_completed": true,
+  "phase": "tasks-generated",
   "approvals": {
     "requirements": {
       "generated": true,
@@ -16,7 +15,7 @@
     },
     "tasks": {
       "generated": true,
-      "approved": true
+      "approved": false
     }
   },
   "ready_for_implementation": true

.kiro/specs/official-docker-image/tasks.md

@@ -166,3 +166,28 @@
   - Confirm that Docker build completes successfully with the replaced `apps/app/docker/Dockerfile`
   - Confirm that existing external references (`codebuild.tf`, `.github/workflows/release.yml`, `ci-app.yml`, `update-readme.sh`) work correctly
   - _Requirements: 8.1, 8.2, 8.3, 8.4_
+
+## Phase 4: Environment variable renaming and README documentation
+
+> Rename the `GROWI_`-prefixed memory management environment variables to `V8_`-prefixed names aligned with V8 option names, and add documentation to the Docker Hub README.
+
+- [ ] 9. Rename environment variables to align with V8 option names
+- [ ] 9.1 (P) Rename all GROWI_-prefixed environment variables to V8_-prefixed names in the entrypoint
+  - Rename `GROWI_HEAP_SIZE` to `V8_MAX_HEAP_SIZE` in the heap size detection function, validation logic, and error messages
+  - Rename `GROWI_OPTIMIZE_MEMORY` to `V8_OPTIMIZE_FOR_SIZE` in the node flag assembly function
+  - Rename `GROWI_LITE_MODE` to `V8_LITE_MODE` in the node flag assembly function
+  - Update the heap size source log message to reflect the new variable name
+  - Update the file header comment documenting the heap size detection fallback chain
+  - _Requirements: 2.1, 2.5, 2.6, 2.7, 6.1, 6.6, 6.7_
+
+- [ ] 9.2 (P) Update all environment variable references in entrypoint unit tests
+  - Update heap size detection tests: replace all `GROWI_HEAP_SIZE` references with `V8_MAX_HEAP_SIZE`
+  - Update node flag assembly tests: replace `GROWI_OPTIMIZE_MEMORY` with `V8_OPTIMIZE_FOR_SIZE` and `GROWI_LITE_MODE` with `V8_LITE_MODE`
+  - Verify all tests pass with the new environment variable names
+  - _Requirements: 2.1, 2.5, 2.6_
+
+- [ ] 10. Add V8 memory management environment variable documentation to README
+  - Add a subsection under Configuration > Environment Variables documenting the three V8 memory management variables
+  - Include variable name, type, default value, and description for each: `V8_MAX_HEAP_SIZE`, `V8_OPTIMIZE_FOR_SIZE`, `V8_LITE_MODE`
+  - Describe the 3-tier heap size fallback behavior (env var → cgroup auto-calculation → V8 default)
+  - _Requirements: 5.1_