✏️ Adjust the options setting of *docker run* command line to be more flexible in usage.

Author: Chisanan232

.github/tag_and_release/intent.yaml

@@ -47,9 +47,8 @@ docker:
     port: 8000                     # Port for container health checks
     path: "/health"                # Health check endpoint path
 
-  application:
-    env_var_name: "API_TOKEN"      # Environment variable name for application
-    env_var_value: "test_token"    # Environment variable value for testing
+  # Flexible Docker run options - supports multiple env vars, volumes, networks, etc.
+  run_options: "-e API_TOKEN=test_token -e DEBUG=true"  # Custom Docker run options for testing
 
 # === VALIDATION CONFIGURATION ===
 validation:
@@ -83,9 +82,13 @@ docs:
 #      health_check:
 #        port: 3000
 #        path: "/api/health"
-#      application:
-#        env_var_name: "CUSTOM_TOKEN"
-#        env_var_value: "custom_test_value"
+#      # Flexible Docker run options - supports any Docker run parameters
+#      run_options: "-e CUSTOM_TOKEN=custom_test_value -e NODE_ENV=production"
+#
+# 4. Advanced Docker configuration examples:
+#    docker:
+#      run_options: "-e API_KEY=test123 -e DB_HOST=localhost -v /tmp:/app/tmp --network mynet"
+#      # Multiple environment variables, volume mounts, custom networks, etc.
 #
 # 4. Documentation versioning examples:
 #    # Legacy format (backward compatible):

.github/workflows/release-staging.yml

@@ -113,8 +113,7 @@ jobs:
       enable-signing: true
       health-check-port: ${{ needs.config.outputs.docker_health_check_port }}
       health-check-path: ${{ needs.config.outputs.docker_health_check_path }}
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   ghcr-rc:
     name: Staging Release to GHCR
@@ -129,8 +128,7 @@ jobs:
       enable-signing: true
       health-check-port: ${{ needs.config.outputs.docker_health_check_port }}
       health-check-path: ${{ needs.config.outputs.docker_health_check_path }}
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   docs-preview:
     uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_docs_operations.yaml@master

.github/workflows/release-validate.yml

@@ -79,8 +79,7 @@ jobs:
       health-check-port: ${{ needs.config.outputs.docker_health_check_port }}
       health-check-path: ${{ needs.config.outputs.docker_health_check_path }}
       enable-signing: true
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   docker-build-ghcr:
     name: Validate GHCR Build
@@ -94,8 +93,7 @@ jobs:
       health-check-port: ${{ needs.config.outputs.docker_health_check_port }}
       health-check-path: ${{ needs.config.outputs.docker_health_check_path }}
       enable-signing: true
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   docs-build:
     uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_docs_operations.yaml@master
@@ -115,8 +113,7 @@ jobs:
       version: ${{ needs.config.outputs.validation_test_version }}
       enable-sbom: true
       enable-signing: true
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   validation-summary:
     name: Validation Summary

.github/workflows/release.yml

@@ -378,8 +378,7 @@ jobs:
       checkout-sha: ${{ needs.bump_version.outputs.new_sha }}
       enable-sbom: true
       enable-signing: true
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   release_docker_ghcr:
     name: Release to GHCR
@@ -393,8 +392,7 @@ jobs:
       checkout-sha: ${{ needs.bump_version.outputs.new_sha }}
       enable-sbom: true
       enable-signing: true
-      app-env-var-name: ${{ needs.config.outputs.docker_app_env_var_name }}
-      app-env-var-value: ${{ needs.config.outputs.docker_app_env_var_value }}
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
   release_docs:
     uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_docs_operations.yaml@master

.github/workflows/rw_docker_operations.yaml

@@ -58,15 +58,10 @@ on:
         required: false
         default: ''
         type: string
-      app-env-var-name:
-        description: 'Application environment variable name for testing'
+      docker-run-options:
+        description: 'Additional Docker run options (environment variables, volumes, networks, etc.)'
         required: false
-        default: 'API_TOKEN'
-        type: string
-      app-env-var-value:
-        description: 'Application environment variable value for testing'
-        required: false
-        default: 'test_token'
+        default: '-e API_TOKEN=test_token'
         type: string
 
     secrets:
@@ -187,7 +182,7 @@ jobs:
           # Start container in background
           docker run -d --name test-container \
             -p ${{ inputs.health-check-port }}:${{ inputs.health-check-port }} \
-            -e ${{ inputs.app-env-var-name }}=${{ inputs.app-env-var-value }} \
+            ${{ inputs.docker-run-options }} \
             $IMAGE_TAG
           
           # Wait for container to be ready and test health endpoint

.github/workflows/rw_parse_project_config.yaml

@@ -124,8 +124,7 @@ jobs:
       docker_registry_ghcr: ${{ steps.parse.outputs.docker_registry_ghcr }}
       docker_health_check_port: ${{ steps.parse.outputs.docker_health_check_port }}
       docker_health_check_path: ${{ steps.parse.outputs.docker_health_check_path }}
-      docker_app_env_var_name: ${{ steps.parse.outputs.docker_app_env_var_name }}
-      docker_app_env_var_value: ${{ steps.parse.outputs.docker_app_env_var_value }}
+      docker_run_options: ${{ steps.parse.outputs.docker_run_options }}
 
       # Validation Configuration
       validation_version: ${{ steps.parse.outputs.validation_version }}
@@ -204,8 +203,20 @@ jobs:
           docker_registry_ghcr=$(get_config ".docker.registries.ghcr" "ghcr.io")
           docker_health_check_port=$(get_config ".docker.health_check.port" "8000")
           docker_health_check_path=$(get_config ".docker.health_check.path" "/health")
-          docker_app_env_var_name=$(get_config ".docker.application.env_var_name" "API_TOKEN")
-          docker_app_env_var_value=$(get_config ".docker.application.env_var_value" "test_token")
+          
+          # Parse flexible Docker run options
+          docker_run_options=$(get_config ".docker.run_options" "-e API_TOKEN=test_token")
+          
+          # Legacy support: If run_options is not set but old env var settings exist, build compatibility string
+          if [[ "$docker_run_options" == "-e API_TOKEN=test_token" ]] && [[ "$use_defaults" == "false" ]]; then
+            legacy_env_name=$(yq eval ".docker.application.env_var_name" "$config_file" 2>/dev/null || echo "null")
+            legacy_env_value=$(yq eval ".docker.application.env_var_value" "$config_file" 2>/dev/null || echo "null")
+            
+            if [[ "$legacy_env_name" != "null" && "$legacy_env_value" != "null" ]]; then
+              docker_run_options="-e ${legacy_env_name}=${legacy_env_value}"
+              echo "⚠️ Using legacy docker.application.env_var_* format. Consider migrating to docker.run_options."
+            fi
+          fi
           
           # Parse Validation Configuration
           validation_version=$(get_config ".validation.version" "1.0.0-validation")
@@ -237,8 +248,7 @@ jobs:
           echo "docker_registry_ghcr=$docker_registry_ghcr" >> $GITHUB_OUTPUT
           echo "docker_health_check_port=$docker_health_check_port" >> $GITHUB_OUTPUT
           echo "docker_health_check_path=$docker_health_check_path" >> $GITHUB_OUTPUT
-          echo "docker_app_env_var_name=$docker_app_env_var_name" >> $GITHUB_OUTPUT
-          echo "docker_app_env_var_value=$docker_app_env_var_value" >> $GITHUB_OUTPUT
+          echo "docker_run_options=$docker_run_options" >> $GITHUB_OUTPUT
           
           echo "validation_version=$validation_version" >> $GITHUB_OUTPUT
           echo "validation_test_version=$validation_test_version" >> $GITHUB_OUTPUT

docs_with_docusarus/contents/development/ci-cd/release-system.mdx

@@ -960,18 +960,34 @@ docker:
   health_check:
     path: "/health"              # string - Health check endpoint
     port: 8000                   # number - Health check port
-  application:
-    env_var_name: "API_TOKEN"    # string - Application environment variable name
-    env_var_value: "test_token"  # string - Application environment variable value
+  run_options: "-e API_TOKEN=test_token -e DEBUG=true -v /host/data:/app/data --network mynetwork"
 ```
 
 **Configuration Options:**
 - **`registries.dockerhub`**: Docker Hub registry URL for dual publishing
 - **`registries.ghcr`**: GitHub Container Registry URL for dual publishing
 - **`health_check.path`**: HTTP health check endpoint path
 - **`health_check.port`**: Port for health check operations
-- **`application.env_var_name`**: Environment variable name for application testing
-- **`application.env_var_value`**: Environment variable value for application testing
+- **`run_options`**: Flexible string for Docker run options (environment variables, volumes, networks, etc.)
+
+**Advanced Docker Run Options Examples:**
+```yaml
+# Basic environment variables
+docker:
+  run_options: "-e API_TOKEN=test_token -e DEBUG=true"
+
+# Multiple environment variables with volumes
+docker:
+  run_options: "-e API_TOKEN=test_token -e DB_URL=postgresql://localhost:5432/app -v /host/data:/app/data -v /host/logs:/app/logs"
+
+# Complex configuration with network and resource limits
+docker:
+  run_options: "-e API_TOKEN=test_token -e REDIS_URL=redis://localhost:6379 --network mynetwork --memory=512m --cpus=0.5 -v /host/config:/app/config:ro"
+
+# Production-ready configuration
+docker:
+  run_options: "-e NODE_ENV=production -e API_TOKEN=prod_token -e DB_URL=postgresql://prod-db:5432/app -e REDIS_URL=redis://prod-redis:6379 --network prod-network --restart unless-stopped -v /data/app:/app/data -v /logs/app:/app/logs"
+```
 
 **Usage in Workflows:**
 ```yaml
@@ -980,15 +996,33 @@ DOCKERHUB_REGISTRY: ${{ needs.config.outputs.docker_registry_dockerhub }}
 GHCR_REGISTRY: ${{ needs.config.outputs.docker_registry_ghcr }}
 HEALTH_CHECK_PATH: ${{ needs.config.outputs.docker_health_check_path }}
 HEALTH_CHECK_PORT: ${{ needs.config.outputs.docker_health_check_port }}
-APP_ENV_NAME: ${{ needs.config.outputs.docker_app_env_name }}
-APP_ENV_VALUE: ${{ needs.config.outputs.docker_app_env_value }}
+DOCKER_RUN_OPTIONS: ${{ needs.config.outputs.docker_run_options }}
+
+# Example: Using the flexible Docker run options in workflows
+jobs:
+  docker-operations:
+    uses: Chisanan232/Template-Python-UV-Project/.github/workflows/rw_docker_operations.yaml@master
+    needs: config
+    with:
+      operation: 'push'
+      registry: ${{ needs.config.outputs.docker_registry_dockerhub }}
+      version: '1.0.0'
+      docker-run-options: ${{ needs.config.outputs.docker_run_options }}
 
 # Example: Health check validation
 - name: Test Health Check
   run: |
     curl -f "http://localhost:${{ needs.config.outputs.docker_health_check_port }}${{ needs.config.outputs.docker_health_check_path }}"
 ```
 
+**Benefits of Flexible Docker Run Options:**
+- **Multiple Environment Variables**: Pass any number of environment variables in a single string
+- **Volume Mounts**: Configure data persistence and file sharing between host and container
+- **Network Configuration**: Specify custom Docker networks for container connectivity
+- **Resource Limits**: Set memory and CPU constraints for container resource management
+- **Runtime Options**: Configure restart policies, security contexts, and other Docker runtime settings
+- **Child Project Flexibility**: Each project using the template can customize Docker behavior without modifying workflows
+
 ##### 9. Validation Configuration
 
 **`validation`** (object)