cboxdk · sylvesterdamgaard · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/docs/cbox-init-integration.md b/docs/cbox-init-integration.md
@@ -27,9 +27,8 @@ Configure Laravel features via environment variables:
 
 ```yaml
 environment:
-  # Laravel optimizations
-  LARAVEL_OPTIMIZE_CONFIG: "true"
-  LARAVEL_OPTIMIZE_ROUTE: "true"
+  # Laravel optimizations (runs config:cache, route:cache, view:cache)
+  LARAVEL_OPTIMIZE_ENABLED: "true"
   LARAVEL_MIGRATE_ENABLED: "true"
 
   # Enable Horizon
@@ -65,8 +64,8 @@ Per-process hooks:
 - Horizon: `horizon:terminate` on shutdown
 
 ### 📊 Health Monitoring
-- **TCP checks** - PHP-FPM (port 9000), Reverb (port 8080)
-- **HTTP checks** - Nginx (port 80 /health)
+- **TCP checks** - PHP-FPM (port 9000), Reverb (port 8080, or 6001 in rootless)
+- **HTTP checks** - Nginx (port 80 /health, or 8080 in rootless)
 - **Exec checks** - Horizon (`php artisan horizon:status`)
 
 ### 🔁 Restart Policies
@@ -94,12 +93,41 @@ Exported on port 9090 at `/metrics`:
 - `cbox_init_scheduled_task_duration_seconds` - Execution duration
 - `cbox_init_scheduled_task_total` - Total runs by status (success/failure)
 
-### 🔌 Management API (Phase 5)
-REST API on port 8080 (when enabled):
-- `GET /api/v1/processes` - List processes
+### 🔌 Management API
+
+REST API for runtime process control (disabled by default for security).
+
+**Enable via environment variable:**
+```yaml
+environment:
+  CBOX_INIT_API_ENABLED: "true"
+  CBOX_INIT_API_PORT: "9180"       # Default: 9180
+```
+
+**Expose the port in docker-compose:**
+```yaml
+services:
+  app:
+    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
+    ports:
+      - "80:80"
+      - "9180:9180"   # Management API
+    environment:
+      CBOX_INIT_API_ENABLED: "true"
+```
+
+**Available endpoints (port 9180):**
+- `GET /api/v1/processes` - List processes and their status
 - `POST /api/v1/processes/{name}/scale` - Dynamic scaling
 - `POST /api/v1/processes/{name}/restart` - Restart process
 
+**Example request:**
+```bash
+curl http://localhost:9180/api/v1/processes
+```
+
+> **Security:** The API gives runtime control over container processes. Avoid exposing port 9180 to the public internet without network-level protection.
+
 ## Architecture
 
 ### Startup Sequence
@@ -157,8 +185,7 @@ services:
   app:
     image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
     environment:
-      LARAVEL_OPTIMIZE_CONFIG: "true"
-      LARAVEL_OPTIMIZE_ROUTE: "true"
+      LARAVEL_OPTIMIZE_ENABLED: "true"
       LARAVEL_MIGRATE_ENABLED: "true"
       CBOX_INIT_PROCESS_HORIZON_ENABLED: "true"
     ports:
@@ -175,10 +202,8 @@ services:
   app:
     image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
     environment:
-      # Laravel optimizations
-      LARAVEL_OPTIMIZE_CONFIG: "true"
-      LARAVEL_OPTIMIZE_ROUTE: "true"
-      LARAVEL_OPTIMIZE_VIEW: "true"
+      # Laravel optimizations (runs config:cache, route:cache, view:cache)
+      LARAVEL_OPTIMIZE_ENABLED: "true"
       LARAVEL_MIGRATE_ENABLED: "true"
 
       # Enable Horizon
@@ -218,10 +243,11 @@ Complete reference: [Environment Variables](./reference/environment-variables)
 
 | Category | Key Variables |
 |----------|---------------|
-| **Laravel Hooks** | `LARAVEL_OPTIMIZE_*`, `LARAVEL_MIGRATE_ENABLED` |
+| **Laravel Hooks** | `LARAVEL_OPTIMIZE_ENABLED`, `LARAVEL_MIGRATE_ENABLED` |
 | **Process Control** | `CBOX_INIT_PROCESS_*_ENABLED` |
 | **Scaling** | `CBOX_INIT_PROCESS_QUEUE_*_SCALE` |
-| **Observability** | `CBOX_INIT_METRICS_ENABLED`, `CBOX_INIT_API_ENABLED` |
+| **Management API** | `CBOX_INIT_API_ENABLED`, `CBOX_INIT_API_PORT` |
+| **Observability** | `CBOX_INIT_METRICS_ENABLED`, `CBOX_INIT_METRICS_PORT` |
 | **Logging** | `CBOX_INIT_LOG_LEVEL`, `CBOX_INIT_LOG_FORMAT` |
 
 ## Monitoring
@@ -495,17 +521,16 @@ services:
       - ./custom-cbox-init.yaml:/app/config/cbox-init.yaml:ro
 ```
 
-### Dynamic Scaling (Phase 5)
+### Dynamic Scaling via API
 
-Via Management API:
+Scale processes at runtime using the Management API (must be enabled first, see [Management API](#-management-api)):
 
 ```bash
 # Scale queue workers to 10 instances
 curl -X POST \
-  -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"replicas": 10}' \
-  http://localhost:8080/api/v1/processes/queue-default/scale
+  http://localhost:9180/api/v1/processes/queue-default/scale
 ```
 
 ### Multiple Queue Types
@@ -534,7 +559,7 @@ If you're migrating from images using Supervisor or S6-Overlay, Cbox Init offers
 - ✅ Native Prometheus metrics
 - ✅ Health checks with automatic restart
 - ✅ Graceful shutdown handling (Horizon: horizon:terminate)
-- ✅ Dynamic scaling via API (Phase 5)
+- ✅ Dynamic scaling via Management API
 - ✅ Dependency management (DAG-based startup order)
 
 **No breaking changes** - Cbox Init is a drop-in replacement.
@@ -588,9 +613,9 @@ Cbox Init v1.0.0 includes:
 - ✅ Structured JSON logging with multiline support
 - ✅ Sensitive data redaction
 - ✅ Scheduled tasks with cron expressions
+- ✅ Management API for runtime process control (disabled by default)
 
 **Coming soon:**
-- Management API for dynamic scaling
 - Grafana dashboard templates
 
 ## Resources

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -188,8 +188,8 @@ environment:
 | Old Variable | New Variable |
 |--------------|--------------|
 | `LARAVEL_SCHEDULER_ENABLED` | `LARAVEL_SCHEDULER` |
-| `LARAVEL_AUTO_OPTIMIZE` | `LARAVEL_OPTIMIZE` |
-| `LARAVEL_AUTO_MIGRATE` | `LARAVEL_MIGRATE` |
+| `LARAVEL_AUTO_OPTIMIZE` | `LARAVEL_OPTIMIZE_ENABLED` |
+| `LARAVEL_AUTO_MIGRATE` | `LARAVEL_MIGRATE_ENABLED` |
 
 ---
 

diff --git a/docs/getting-started/faq.md b/docs/getting-started/faq.md
@@ -56,7 +56,7 @@ OPcache with JIT, realpath cache, Nginx open file cache, gzip compression, and p
 First requests trigger OPcache warming and framework bootstrapping. Enable warm-up in production:
 ```yaml
 environment:
-  LARAVEL_AUTO_OPTIMIZE: "true"  # Runs optimize on startup
+  LARAVEL_OPTIMIZE_ENABLED: "true"  # Runs config:cache, route:cache, view:cache on startup
 ```
 
 ## Security

diff --git a/docs/guides/production-deployment.md b/docs/guides/production-deployment.md
@@ -49,7 +49,7 @@ services:
 
       # Laravel Production
       - LARAVEL_SCHEDULER=true
-      - LARAVEL_AUTO_OPTIMIZE=true
+      - LARAVEL_OPTIMIZE_ENABLED=true
       - APP_ENV=production
       - APP_DEBUG=false
 ```

diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md
@@ -372,6 +372,29 @@ secrets:
 
 ---
 
+## Cbox Init Management API
+
+The Management API provides runtime control over container processes (list, scale, restart). It is **disabled by default** for security.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CBOX_INIT_API_ENABLED` | `false` | Enable the Management API |
+| `CBOX_INIT_API_PORT` | `9180` | Port the API listens on |
+
+```yaml
+services:
+  app:
+    image: ghcr.io/cboxdk/php-baseimages/php-fpm-nginx:8.4-bookworm
+    ports:
+      - "9180:9180"
+    environment:
+      CBOX_INIT_API_ENABLED: "true"
+```
+
+See [Cbox Init Integration](../cbox-init-integration#-management-api) for endpoints and examples.
+
+---
+
 ## Other Settings
 
 | Variable | Default | Description |

diff --git a/docs/troubleshooting/migration-guide.md b/docs/troubleshooting/migration-guide.md
@@ -54,7 +54,7 @@ AUTORUN_ENABLED=true
 AUTORUN_LARAVEL_STORAGE_LINK=true
 
 # Cbox
-LARAVEL_AUTO_OPTIMIZE=true
+LARAVEL_OPTIMIZE_ENABLED=true
 # (storage link runs automatically)
 ```
 
@@ -263,7 +263,7 @@ COPY docker-entrypoint-init.d/ /docker-entrypoint-init.d/
 # Add Laravel-specific settings
 environment:
   - LARAVEL_SCHEDULER=true
-  - LARAVEL_AUTO_OPTIMIZE=true
+  - LARAVEL_OPTIMIZE_ENABLED=true
   - LARAVEL_QUEUE=true
 ```
 

diff --git a/php-fpm-nginx/common/docker-entrypoint.sh b/php-fpm-nginx/common/docker-entrypoint.sh
@@ -200,6 +200,7 @@ map_env_aliases() {
     [ -n "$LARAVEL_QUEUE_HIGH" ] && validate_boolean "$LARAVEL_QUEUE_HIGH" && export CBOX_INIT_PROCESS_QUEUE_HIGH_ENABLED="$LARAVEL_QUEUE_HIGH"
     # Backward compatibility
     [ -n "$LARAVEL_SCHEDULER_ENABLED" ] && export CBOX_INIT_PROCESS_SCHEDULER_ENABLED="$LARAVEL_SCHEDULER_ENABLED"
+    [ -n "$LARAVEL_AUTO_OPTIMIZE" ] && export LARAVEL_OPTIMIZE_ENABLED="$LARAVEL_AUTO_OPTIMIZE"
     [ -n "$LARAVEL_AUTO_MIGRATE" ] && export LARAVEL_MIGRATE_ENABLED="$LARAVEL_AUTO_MIGRATE"
     return 0
 }
@@ -454,6 +455,39 @@ EOF
     return 0
 }
 
+###########################################
+# Cbox Init Environment Variable Overrides
+# The Go binary reads global config from YAML only (no env binding for
+# api_enabled, api_port, etc.). This function copies the template config
+# to /tmp and patches it with sed so that env vars like
+# CBOX_INIT_API_ENABLED actually take effect.
+###########################################
+apply_cbox_init_env_overrides() {
+    local src="${CBOX_INIT_CONFIG:-/etc/cbox-init/cbox-init.yaml}"
+    local dst="/tmp/cbox-init.yaml"
+
+    [ ! -f "$src" ] && return 0
+
+    cp "$src" "$dst"
+
+    # Management API overrides
+    [ -n "$CBOX_INIT_API_ENABLED" ] && sed -i "s/^\(\s*\)api_enabled:.*/\1api_enabled: ${CBOX_INIT_API_ENABLED}/" "$dst"
+    [ -n "$CBOX_INIT_API_PORT" ] && sed -i "s/^\(\s*\)api_port:.*/\1api_port: ${CBOX_INIT_API_PORT}/" "$dst"
+
+    # Metrics overrides
+    [ -n "$CBOX_INIT_METRICS_ENABLED" ] && sed -i "s/^\(\s*\)metrics_enabled:.*/\1metrics_enabled: ${CBOX_INIT_METRICS_ENABLED}/" "$dst"
+    [ -n "$CBOX_INIT_METRICS_PORT" ] && sed -i "s/^\(\s*\)metrics_port:.*/\1metrics_port: ${CBOX_INIT_METRICS_PORT}/" "$dst"
+
+    # Logging overrides
+    [ -n "$CBOX_INIT_LOG_LEVEL" ] && sed -i "s/^\(\s*\)log_level:.*/\1log_level: ${CBOX_INIT_LOG_LEVEL}/" "$dst"
+    [ -n "$CBOX_INIT_LOG_FORMAT" ] && sed -i "s/^\(\s*\)log_format:.*/\1log_format: ${CBOX_INIT_LOG_FORMAT}/" "$dst"
+
+    # Shutdown timeout override
+    [ -n "$CBOX_INIT_SHUTDOWN_TIMEOUT" ] && sed -i "s/^\(\s*\)shutdown_timeout:.*/\1shutdown_timeout: ${CBOX_INIT_SHUTDOWN_TIMEOUT}/" "$dst"
+
+    export CBOX_INIT_CONFIG="$dst"
+}
+
 ###########################################
 # Cbox Init Validation
 # NOTE: Similar to validate_cbox_init() from entrypoint-lib.sh but uses
@@ -617,6 +651,7 @@ fi
 
 # Start Cbox Init
 CBOX_INIT_CONFIG="${CBOX_INIT_CONFIG:-/etc/cbox-init/cbox-init.yaml}"
+apply_cbox_init_env_overrides
 log_info "Starting Cbox Init process manager"
 log_info "Config: $CBOX_INIT_CONFIG"