Merge pull request #108 from udx/supervisord-config-improvements

supervisord program improvement: Ensure child processes are terminated on stop/restart

Author: fqjony

.github/workflows/release.yml

@@ -39,7 +39,7 @@ jobs:
           driver: docker-container
 
       - name: Install GitVersion
-        uses: gittools/actions/gitversion/setup@v4.1.0
+        uses: gittools/actions/gitversion/setup@v4.2.0
         with:
           versionSpec: "6.1.0"
 
@@ -48,7 +48,7 @@ jobs:
 
       - name: Determine Version
         id: gitversion
-        uses: gittools/actions/gitversion/execute@v4.1.0
+        uses: gittools/actions/gitversion/execute@v4.2.0
         with:
           useConfigFile: true
           configFilePath: ci/git-version.yml

Dockerfile

@@ -76,16 +76,16 @@ RUN echo $TZ > /etc/timezone && \
 # Install yq (architecture-aware)
 RUN ARCH=$(uname -m) && \
     if [ "$ARCH" = "x86_64" ]; then ARCH="amd64"; elif [ "$ARCH" = "aarch64" ]; then ARCH="arm64"; fi && \
-    curl -sL https://github.com/mikefarah/yq/releases/download/v4.48.1/yq_linux_${ARCH}.tar.gz | tar xz && \
+    curl -sL https://github.com/mikefarah/yq/releases/download/v4.48.2/yq_linux_${ARCH}.tar.gz | tar xz && \
     mv yq_linux_${ARCH} /usr/bin/yq && \
     rm -rf /tmp/*
 
 # Install Google Cloud SDK (architecture-aware)
 RUN ARCH=$(uname -m) && \
     if [ "$ARCH" = "x86_64" ]; then \
-    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-545.0.0-linux-x86_64.tar.gz" -o google-cloud-sdk.tar.gz; \
+    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-547.0.0-linux-x86_64.tar.gz" -o google-cloud-sdk.tar.gz; \
     elif [ "$ARCH" = "aarch64" ]; then \
-    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-545.0.0-linux-arm.tar.gz" -o google-cloud-sdk.tar.gz; \
+    curl -sSL "https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-sdk-547.0.0-linux-arm.tar.gz" -o google-cloud-sdk.tar.gz; \
     fi && \
     tar -xzf google-cloud-sdk.tar.gz && \
     ./google-cloud-sdk/install.sh -q && \

docs/services.md

@@ -12,22 +12,24 @@ The UDX Worker uses `services.yaml` to define and manage multiple services. Each
 
 ## Configuration Structure
 
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `kind` | string | Yes | - | Must be `workerService` |
-| `version` | string | Yes | - | Must be `udx.io/worker-v1/service` |
-| `services` | array | Yes | - | List of service definitions |
+| Field      | Type   | Required | Default | Description                        |
+| ---------- | ------ | -------- | ------- | ---------------------------------- |
+| `kind`     | string | Yes      | -       | Must be `workerService`            |
+| `version`  | string | Yes      | -       | Must be `udx.io/worker-v1/service` |
+| `services` | array  | Yes      | -       | List of service definitions        |
 
 ### Service Definition Fields
 
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `name` | string | Yes | - | Unique service identifier |
-| `command` | string | Yes | - | Command to execute |
-| `ignore` | boolean | No | `false` | Skip service management |
-| `autostart` | boolean | No | `true` | Start on worker launch |
-| `autorestart` | boolean | No | `false` | Restart on failure |
-| `envs` | array | No | `[]` | Environment variables |
+| Field         | Type    | Required | Default | Description               |
+| ------------- | ------- | -------- | ------- | ------------------------- |
+| `name`        | string  | Yes      | -       | Unique service identifier |
+| `command`     | string  | Yes      | -       | Command to execute        |
+| `ignore`      | boolean | No       | `false` | Skip service management   |
+| `autostart`   | boolean | No       | `true`  | Start on worker launch    |
+| `autorestart` | boolean | No       | `false` | Restart on failure        |
+| `envs`        | array   | No       | `[]`    | Environment variables     |
+| `stopasgroup` | boolean | No       | `false` | Stop process group        |
+| `killasgroup` | boolean | No       | `false` | Kill process group        |
 
 ## Basic Example
 
@@ -53,9 +55,11 @@ kind: workerService
 version: udx.io/worker-v1/service
 services:
   - name: "api-server"
-    command: "node api/server.js"
+    command: "npm start"
     autostart: true
     autorestart: true
+    stopasgroup: true
+    killasgroup: true
     envs:
       - "PORT=3000"
       - "NODE_ENV=production"
@@ -68,7 +72,7 @@ services:
 
   - name: "monitoring"
     command: "./monitor.sh"
-    ignore: true  # Temporarily disabled
+    ignore: true # Temporarily disabled
 ```
 
 ### Service with Complex Command
@@ -87,16 +91,19 @@ services:
 ## Best Practices
 
 1. **Service Naming**
+
    - Use descriptive, lowercase names
    - Separate words with hyphens
    - Keep names concise but meaningful
 
 2. **Command Definition**
+
    - Use absolute paths when possible
    - Quote commands with spaces or special characters
    - Consider using shell scripts for complex commands
 
 3. **Environment Variables**
+
    - Use uppercase for variable names
    - Group related variables together
    - Document required variables
@@ -110,39 +117,43 @@ services:
 
 When running `worker service list`, services show the following status indicators:
 
-| Symbol | Status | Description |
-|--------|---------|-------------|
-| ✅ | RUNNING | Service is running normally |
-| ⛔ | STOPPED | Service was stopped with `worker service stop` |
-| 💀 | FATAL | Service exited (any exit code) |
-| 🔄 | RETRY | Service is retrying (with autorestart: true) |
-| ⚠️ | STARTING | Service is starting up |
+| Symbol | Status   | Description                                    |
+| ------ | -------- | ---------------------------------------------- |
+| ✅     | RUNNING  | Service is running normally                    |
+| ⛔     | STOPPED  | Service was stopped with `worker service stop` |
+| 💀     | FATAL    | Service exited (any exit code)                 |
+| 🔄     | RETRY    | Service is retrying (with autorestart: true)   |
+| ⚠️     | STARTING | Service is starting up                         |
 
 ### Service Types
 
 1. **Long-running Services**
+
    ```yaml
    - name: "web-server"
      command: "python server.py"
-     autorestart: true    # Restarts on exit
+     autorestart: true # Restarts on exit
    ```
+
    - Shows as RUNNING (✅) while active
    - Shows as RETRY (🔄) then FATAL (💀) if it keeps failing
 
 2. **One-shot Tasks**
    ```yaml
    - name: "setup"
      command: "./setup.sh"
-     autorestart: false   # Runs once
+     autorestart: false # Runs once
    ```
    - Use `worker service stop` for clean completion (⛔)
    - Otherwise shows as FATAL (💀) after exit
 
 Note: Exit codes (0 or non-zero) don't affect the final status. What matters is:
+
 - Whether the service keeps running (RUNNING ✅)
 - How it stops (STOPPED ⛔ vs FATAL 💀)
 
 Example:
+
 ```bash
 # Long-running service and one-shot task
 $ worker service list
@@ -171,4 +182,4 @@ worker service logs web-server
 
 # Restart a service
 worker service restart web-server
-```
+```

etc/configs/supervisor/program.conf

@@ -6,6 +6,10 @@ autorestart=${autorestart}
 startretries=${startretries}
 startsecs=1          # Consider process started if it runs for at least 1 second
 
+# Kill process group
+stopasgroup=${stopasgroup}
+killasgroup=${killasgroup}
+
 # Logging settings
 stdout_logfile=/var/log/supervisor/${process_name}.out.log
 stdout_logfile_maxbytes=50MB

lib/process_manager.sh

@@ -61,6 +61,11 @@ parse_service_info() {
     autorestart=$(echo "$service_json" | jq -r '.autorestart // "false"')
     # Ensure 'envs' defaults to an empty array if not specified
     envs=$(echo "$service_json" | jq -r '.envs // [] | join(",")')
+
+    # Use 'false' as default for 'stopasgroup' if not specified
+    stopasgroup=$(echo "$service_json" | jq -r '.stopasgroup // "false"')
+    # Use 'false' as default for 'killasgroup' if not specified
+    killasgroup=$(echo "$service_json" | jq -r '.killasgroup // "false"')
 
     # Ignore the service if 'ignore' is set to "true"
     if [[ "$ignore" == "true" ]]; then
@@ -95,7 +100,9 @@ parse_service_info() {
         s|\${autostart}|$autostart|g; \
         s|\${autorestart}|$autorestart|g; \
         s|\${startretries}|$startretries|g; \
-        s|\${envs}|$envs|g" "$PROGRAM_TEMPLATE_FILE" >> "$FINAL_CONFIG"
+        s|\${envs}|$envs|g; \
+        s|\${stopasgroup}|$stopasgroup|g; \
+        s|\${killasgroup}|$killasgroup|g" "$PROGRAM_TEMPLATE_FILE" >> "$FINAL_CONFIG"
 }
 
 # Function to check if services are active